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)

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)

// 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