# byr (try v2)

## introductory references
* https://tom-vykes.medium.com/the-worst-things-about-github-8e8efc60fae3
  * Log spam
  * Pull Requests and Merging is language is absurdly confusing
  * Feature branches are totally flawed and cause work in isolation
  * The “advantage” of working offline is.. frankly stupid
  * Unstaged, Staged, Commit
  * Working on multiple projects requires multiple clones
  * Remote vs. Local Repository makes time travel look like child’s play (too many versions of branches)
  * Undoing commits is a nightmare
  * conclusion: monorepo, 2 branches (`main` vs `stable`)

## features wanted on server side
* monorepo, with a main branch and others which are all cherry-picked from that (a full fork is necessary to deviate); restriction to just subsequences is good. (avoid accidental deviation)
* snapshots (compressed "checkouts" basically, to avoid having to replay all of history on any complex actions) and patches (scripts, run in sandbox)
* hooks, e.g. post-patch
* patches can be in multiple states:
  * "applied" (contained in main)
  * "unreviewed" (not in main, active)
  * "rejected/abandoned" (not in main, inactive)

## features wanted on client side
* patches can be in multiple states:
  * "applied" (as above)
  * "submitted" (pushed to server, but not applied)
  * "unsubmitted" (not pushed to server)
* local tree can be in multiple states: "commited", "uncommited" (current state is not completely recorded in a commit)
* no staging area, but using multiple trees should be easy
* no "untracked" data, enforce proper use of `.ignore` files

## resulting design

### patch states

* applied: contained in main, frozen
* unreviewed: not in main, active
* rejected/abandoned: not in main, inactive
* submitted is equal to {unreviewed or abandoned}
* unsubmitted

Patches can be frozen (when they are a linked to a single snapshot),
or be not-frozen (when they are linked to a command which gets automatically rebased)

```rust
enum PatchAct {
    Frozen(Snapshot),
    Dynamic(Command),
}

enum PatchInject {
    InStable,
    InMain,
    Unreviewed,
    Abandoned,
    Unsubmitted,
}

struct PatchState {
    inj: PatchInject,
    act: PatchAct,
}
```

### CLI user interface

reviewed changes all have two identifiers: their publishing (-> "unreviewed") revision (`pub#[0-9]+`)
and the position in `main`, `main#[0-9]+`; there also exist local changes (`local#[0-9]+`).
exclusion only based upon stuff in branch; inclusion only based upon publishing revision.
A change belongs to a single server.

it is possible to define pre-diff hooks (e.g. auto-format all code) and post-apply hooks (e.g. run CI)

```console
// user-local "remote" registration
// maybe use workspaces?
$ byr remote add [--dup=full|latest] $RNAME $URL
[$ byr remote set [--dup=full|latest] $RNAME]

// pulls data from remoe explicitly,
// should be usually unnecessary
$ byr fetch [$RNAME]

// removes the content of $DIR and replaces it with the current content of $BRANCH
$ byr co|checkout [-C $DIR] [-R $RNAME] [-B $BRANCH] [-I $LIST_OF_ADDITIONALLY_INCLUDED_CHANGES] [-E $LIST_OF_EXCLUDED_CHANGES]

// applies a patch script to a checkout, recording that in a change
$ byr a[pply] -m "change description" -s $PATCH_SCRIPT

// translates the current change into a diff, recording that in a change
$ byr a[pply] -m "change description" --diff

// upload newer changes to $RNAME
$ byr pub[lish] $RNAME

// mark a change as private to prevent it from being pushed to any server
$ byr private $CHANGE_ID
```