X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=topbloke.git;a=blobdiff_plain;f=DESIGN;h=b7c677d51e5bd7c7e943214739cbae8cd135bd46;hp=f03febbfa8019d4642e7e47b10939b8d963e74a0;hb=effecc36db10d6fe9562097242d60e2be102407a;hpb=2c7894055e45c927157bd8c3454a78fbe095e123 diff --git a/DESIGN b/DESIGN index f03febb..b7c677d 100644 --- a/DESIGN +++ b/DESIGN @@ -1,17 +1,17 @@ Basic update algorithm: 1. recurse to all of our direct dependencies and - update their bases and branches + update their bases and tips 2. Update our base. - i. Compute our base's set of desired included branches: - The set of desired included branches for a base - is the union of the desired included branches for each + i. Compute our base's set of desired included deps: + The set of desired included deps for a base + is the union of the desired included deps for each branch named in the base's branch's direct deps, plus the name of every direct external dep. - The set of desired included branches for a branch - is the set of desired included branches for the branch's + The set of desired included deps for a branch + is the set of desired included deps for the branch's base plus the branch name itself. ii. For each source in the best order, do the following merge: @@ -23,15 +23,15 @@ Basic update algorithm: Check for unwanted dependency removals. An unwanted dependency removal is - A branch in the desired included branches - Which exists in the common ancestor's actual included branches - but which is missing in the source's actual included branches + A branch in the desired included deps + Which exists in the common ancestor's actual included deps + but which is missing in the source's actual included deps (NB that this definition excludes dependency removals which have already occurred on our base; these will be reverted later.) For each unwanted dependency removal (ie for each such branch), find the most recent commit which unwantedly removed - the dep from the source's actual included branches ("relevant + the dep from the source's actual included deps ("relevant unwanted removal commit"). (Abort if any such commit is a merge.) Select the earliest relevant unwanted removal commit (from the set of relevant unwanted removal commits @@ -44,8 +44,8 @@ Basic update algorithm: tries to keep the unwanted dependency removal's reversions as close as possible to their originating points. The recursion, which processes dependencies before their clients, - tries to keep the reversion churn localised: client branches - of a branch affected by an unwanted removal will benefit from + tries to keep the reversion churn localised: client patches + of a patch affected by an unwanted removal will benefit from that client's resolution of the situation.) Now continue to the next unwanted dependency removal. @@ -55,8 +55,8 @@ Basic update algorithm: iii. Check for missing or unwanted dependency inclusions. Compare - our base's desired included branches with our base's actual - included branches. In exceptional conditions, they will not + our base's desired included deps with our base's actual + included deps. In exceptional conditions, they will not be identical. This can happen, for example, because a dependency removal was incorporated into our base branch but the removed branch was introduced as an explicit dependency. @@ -98,55 +98,64 @@ merging from local branches first. "Recency" refers to the order from git-rev-list --date-order. -Actual included branches: +Actual included deps: - This is tracked explicitly in .topgit/included, one branch per + This is tracked explicitly in .topbloke/included, one branch per line. For compatibility with older versions, every time we think about a base, branch or source above, we check whether - .topgit/included is present. + .topbloke/included is present. If it isn't then we calculate a child commit which has a - .topgit/included. In the case of a remote branch or base, we + .topbloke/included. In the case of a remote branch or base, we substitute this child commit for the relevant remote ref but do not record it in the remote ref; in the case of a local branch or base, we advance the local branch or base accordingly. - When .topgit/included is calculated in this way, it always gets - the list of desired included branches. (Older versions of topgit, - which do not support dependency deletion, always have exactly the - desired branches actually included.) + When .topbloke/included is calculated in this way, it always gets + the list of desired included deps. (topgit, + which does not support dependency deletion, always has exactly the + desired deps actually included.) + Foreign branches cannot be removed from included and cannot + therefore be removed from dependency lists. -Branch removal: - - removed branch must be removed from the deps of its +Patch removal: + + - removed patch must be removed from the deps of its ex-children, and replaced with the deps of the removed - branch + patch - - removed branch wants not to be in list of branches "git-branch" + - removed patch wants not to be in list of patches "tb-list" et al any more - branches in refs/top-branches ? yes - deleted branches do something to the base ? no + branches in refs/topbloke-tips ? yes + deleted patches do something to the base ? no - deleting empty branch: dependencies fine - deleting nonempty branch: if any dependencies found, their + deleting empty patch: dependencies fine + deleting nonempty patch: if any dependencies found, their updates break purpose of deleting? - - remove from views of active branches + - remove from views of active patches - prevent new commits - - remove from dependencies of active branches - only makes sense if no active branches depend on it. + - remove from dependencies of active patches + only makes sense if no active patches depend on it. undeleting - - just unmark the branch as deleted + - just unmark the patch as deleted + + +Foreign branches: + When merging from a foreign dependency, check that it + does not have .topbloke metadata; LATER if it + does, could produce a new commit which has .topbloke removed + and merge from that -Branch naming: +Patch naming: needs to be globally unique so put email address in it - also "tree" or "context" name, found automatically -tg operations search for applicable branches -safe charset for branch names +tg operations search for applicable patches +safe charset for patch names . - / 0-9 a-z not permitted (git-check-ref-format(1)) spc ~ ^ : ? * [ \ @@ -154,7 +163,7 @@ not permitted (git-check-ref-format(1)) (apropos of shell) -When pulling, which remotes get to update which branches ? +When pulling, which remotes get to update which patches ? Complicated question! For now, have "blessed" remotes, which we always pull and update from. @@ -166,7 +175,7 @@ algorithm ? Concept of a "stack" ? -Unnecessary - instead, deal with leaf branches +Unnecessary - instead, deal with leaf patches Operations like "go up the stack", goes towards leaf. Hopefully unique. "Down" the stack, uses a "conventional" linearisation Stack reordering op ? auto adjust deps