create works again

[topbloke.git] / FORMAT

diff --git a/FORMAT b/FORMAT
index 8729990dc79a75ccd5119d35afc4b5d4451767b9..276051d5d1a046e54288956ac6f5d0dff0ed618a 100644 (file)
--- a/FORMAT
+++ b/FORMAT
@@ -11,24 +11,29 @@ 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:
                                <topbloke patch name>
                                - <ref name including refs/heads/>
-                       exist only in base branch
-
-       deleted         exists (but empty) if branch is deleted
-                       exist only in tip branch
+                       exists only in base branch
 
-       patch-          name of this topbloke patch (plus a newline)
-                       exists in base and tip, identical value
+       deleted         exists (but empty) if patch is deleted
+                       exists only in tip branch
 
-       topgit-         name of the topgit branch that this was
-                       imported from and which we should merge from
-                       (plus a newline)
-                       exist only in base branch
+#TBD#  topgit-         name of the topgit branch that this was
+#TBD#                  imported from and which we should merge from
+#TBD#                  (plus a newline)
+#TBD#                  exists only in base branch
 
        [^+]*-          another property that applies to this patch;
                        if not known to this version of topbloke then it
@@ -44,9 +49,19 @@ In-tree, there are metadata files in .topbloke
     have names starting with "+":
 
        +included       actual included deps, one per line
-                       format as for deps
+                       format as for deps, only includes topbloke patches
                        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 ?