patch mgmt thoughts

[topbloke.git] / FORMAT

diff --git a/FORMAT b/FORMAT
index 8729990dc79a75ccd5119d35afc4b5d4451767b9..75896b76ff33b90adf516734b94554f934f816cd 100644 (file)
--- a/FORMAT
+++ b/FORMAT
@@ -11,7 +11,15 @@ In-tree, there are metadata files in .topbloke
     or changes from bases or dependencies:
 
        msg             patch "commit message"
-                       exist only in tip branch
+                       exists only in tip branch
+                       EDITED BY USER
+
+       patch           name of this topbloke patch (plus a newline)
+                       exists in base and tip, identical value
+
+       base            commit id of corresponding base B(C)
+                       exists only in tip branch
+                       this is how we tell tip from base commits
 
        deps            direct dependencies, one per line
                        as either:
@@ -19,12 +27,9 @@ In-tree, there are metadata files in .topbloke
                                - <ref name including refs/heads/>
                        exist only in base branch
 
-       deleted         exists (but empty) if branch is deleted
+       deleted         exists (but empty) if patch is deleted
                        exist only in tip branch
 
-       patch-          name of this topbloke patch (plus a newline)
-                       exists in base and tip, identical value
-
        topgit-         name of the topgit branch that this was
                        imported from and which we should merge from
                        (plus a newline)
@@ -47,6 +52,16 @@ In-tree, there are metadata files in .topbloke
                        format as for deps
                        exists in tip and base branches
 
+       +ends           list of ends E(C,Px+)
+                       format is one line per Px for which E(C,Px+) != { }
+                       the line contains the patch name Px plus
+                        the commit object names for E(C,Px+),
+                        separated by spaces
+                       in the case of tip commits, the commit's patch
+                        is not listed; for these implicitly E(C,Px+) = { C }
+                       always exists in tip and base branches, perhaps as
+                        an empty file
+
        +*-             another property that is inherited; it is also
                        safe to:
                         - merge this file as text when merging
@@ -126,6 +141,15 @@ Patches may be specified with this grammar:
    email-local-part := has the syntax of a valid git ref name 
                        without any '@' or '/' or ','
 
+
+Patch specification semantics:
+
+ * Calling context provides a scope, which restricts the set of
+   possible patches.
+ * If no email address in spec, look for patches in that set whose email
+   address is the same as the user's email address.
+ * ... ???
+
 Search algorithm:
        1. prefer patches with email address (or domain)
           matching current patch
@@ -164,3 +188,18 @@ then all of the following can refer to the same patch
        ijackson@/reorg/sponge
        ijackson@/2012/reorg/sponge
        ijackson@chiark.greenend.org.uk/reorg/sponge
+
+
+Other notes re searching and patch identification:
+
+
+??? if using series defined by tips, how to stop other people stealing
+ our tips  -  
+
+have a way to limit refs pull by email address have a way to limit
+head overlappingness by email address pairs, stops other people
+extending your series
+
+series name in each patch ?  some patches marked as definitely series tip ?
+some bases marked as definitively series base ?
+"insert after this patch, rewrite all deps everywhere" option ?