chiark / gitweb /
change terminology
[topbloke.git] / DESIGN
diff --git a/DESIGN b/DESIGN
index 23d5a16..b7c677d 100644 (file)
--- 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,7 +98,7 @@ 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 .topbloke/included, one branch per
   line.  For compatibility with older versions, every time we think
@@ -112,42 +112,50 @@ Actual included branches:
   base, we advance the local branch or base accordingly.
 
   When .topbloke/included is calculated in this way, it always gets
-  the list of desired included branches.  (topgit,
+  the list of desired included deps.  (topgit,
   which does not support dependency deletion, always has exactly the
-  desired branches actually included.)
+  desired deps actually included.)
 
-  Non-topbloke-controlled branches are never recorded in included.
+  Foreign branches cannot be removed from included and cannot
+  therefore be removed from dependency lists.
 
 
-Branch removal:
+Patch removal:
 
- - removed branch must be removed from the deps of its
+ - 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
 
-Branch naming:
+
+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
+
+Patch naming:
  needs to be globally unique
  so put email address in it
-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 ~ ^ : ? * [ \
@@ -155,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.
@@ -167,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