Some thoughts

[topbloke.git] / DESIGN

diff --git a/DESIGN b/DESIGN
index f03febbfa8019d4642e7e47b10939b8d963e74a0..b7c677d51e5bd7c7e943214739cbae8cd135bd46 100644 (file)
--- a/DESIGN
+++ b/DESIGN
@@ -1,17 +1,17 @@
 Basic update algorithm:
 
  1. recurse to all of our direct dependencies and
 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.
 
 
  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.
          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:
          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
 
        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
           (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
        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 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.
        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
 
     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.
        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.
 
      
 "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
   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
 
   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.
 
   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
    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
    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?
     updates break
 
  purpose of deleting?

-   - remove from views of active branches
+   - remove from views of active patches

    - prevent new commits
    - 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
 
  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
  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 ~ ^ : ? * [ \
   . - / 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)
 
 
  (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.
 Complicated question!
 
 For now, have "blessed" remotes, which we always pull and update from.


@@ -166,7 +175,7 @@ algorithm ?
 
 
 Concept of a "stack" ?
 
 
 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
 Operations like "go up the stack", goes towards leaf.  Hopefully unique.
 "Down" the stack, uses a "conventional" linearisation
 Stack reordering op ?  auto adjust deps