chiark / gitweb /
better
[git-hash-transition-plan.git] / plan.txt
index 9e2037b..b4c622b 100644 (file)
--- a/plan.txt
+++ b/plan.txt
@@ -113,11 +113,9 @@ transition plan.)
 
 ORDERING
 
-Hash functions are partially ordered, from `older' to `newer'.
-
-The ordering is configurable.  The default, with the two hash
-functions defined here, is the obvious ordering
-    SHA1 ([0-9a-f]*) < BLAKE2b (H*)
+Hash functions are partially ordered, from `worse' to `better'.
+The ordering is configurable.  For details of the defaults,
+see _Transition Plan_.
 
 
 CHOICE OF SUBNAMESPACE
@@ -255,18 +253,6 @@ behaviours, according to configuration:
      introduction of vulnerable data generated by badly configured
      clients.
 
-  (d) forgotten: such objects are not stored.  References to such
-      objects return dummy objects of the right shape: the empty blob;
-      the empty tree; a root commit with an empty tree and dummy
-      metadata.  This allows us to finally retire a hash function
-      entirely.  We effectively throw away all the history which uses
-      this hash function.
-
-During transfer protocols, the receiver will say which hashes it
-thinks are forgotten, and the sender will not follow such references
-when computing the set of objects to send.  So receivers will not
-receive the forgotten objects.
-
 
 Remote protocol
 
@@ -288,92 +274,101 @@ git diff is needed, or explicit generation of a tree object with the
 right hash.
 
 
-Transition plan
+TRANSITION PLAN
+
+(For brevity I will write `SHA' for hashing with SHA-1, using current
+unqualified object names, and `BLAKE' for hasing with BLAKE2b, using
+H<hex> object names.)
 
 Y0: Implement all of the above.  Test it.
 
     Default configuration:
-       SHA-1 is enabled
-       SHA-512 is disabled in trees without working trees
-       SHA-512 is enabled in trees with working trees
+       SHA is enabled
+       BLAKE is disabled in trees without working trees
+       BLAKE is enabled in trees with working trees
+       SHA > BLAKE
 
     Effects:
 
-    Existing projects will not switch to SHA-512 willy-nilly.
-    New projects will still use SHA-1.
+    Clients are prepared to process BLAKE data, but it is not
+    generated by default and cannot be pushed to servers.
 
-    Incompatible new-style commits cannot be pushed without server
-    admin effort (or until future upgrade).
+    All old git clients still work.
 
-    So all old git clients still work.
-
-Y4: SHA-512 by default for new projects.
+Y4: BLAKE by default for new projects.
     Conversion enabled for existing projects.
-    Old git software is now pretty firmly deprecated.
+    Old git software is going to start rotting.
 
     Default configuration change:
+       BLAKE > SHA
+       BLAKE enabled (even in trees without working trees)
 
-       When creating a new bare tree, a configuration dropping is left
-       (in `config') which specifies that SHA-1 is OBSOLESCENT
-
-       Default status for SHA-512 is FORBIDDEN if SHA-1 is ENABLED,
-       or ENABLED if SHA-1 is OBSOLESCENT.
-
-       default HEAD hash is newest ENABLED hash.
+    Suggested bulk hosting site configuration change:
+       Newly created projects should get BLAKE enabled
+       Existing projects should retain BLAKE disabled by default
+       Button should be provided to start conversion (see below)
 
     Effects:
 
-    When creating a new working tree, it starts using SHA-512.
-    A new server tree will accept SHA-512.
+    When creating a new working tree, it starts using BLAKE.
 
-    Existing server trees do not yet accept SHA-512.  They publish
-    their SHA-1 hashes, so clients make commits with SHA-1.
+    Servers which have been updated will accept BLAKE.
 
-    To convert a project, an administrator would set SHA-1 to
-    OBSOLESCENT on the server.  All clones after that will have HEAD
-    with a SHA-512 name.  Fetches and pulls will update to SHA-512
-    names.
+    Servers which have not been updated to Y4's git will need a small
+    configuration change (enabling BLAKE) to cope with the new
+    projects that are using BLAKE.
 
-will , and push one SHA-512 commit to
-    mainline.
+    To convert a project, an administrator (or project owner) would
+    set BLAKE to enabled, and SHA to deprecated, on the server.  On
+    the next pull the server will provide ref hints naming BLAKE,
+    which will get copied to the user's HEAD.  So the user is infected
+    with BLAKE.
 
+    To convert a project branch-by-branch, the administrator would set
+    BLAKE to enabled but leave SHA enabled.  Then each branch retains
+    its own hash.  A branch can be converted by pushing a BLAKE commit
+    to it, or by setting a ref hint on the server.
 
+Y6: BLAKE by default for all projects
+    Existing projects start being converted infectiously.
+    It is hard for a project to stop this happening if any of
+     their servers are updated.
+    Old git software is firmly stuffed.
 
-    Default configuration change:
+    Default configuration change
+       SHA deprecated in trees without working trees
 
     Effects:
 
-    When creating a new tree with working tree with git init (ie, no
-    HEAD), the default HEAD hash is set to SHA-512 (because SHA-1 is
-    OBSOLESCENT in a new tree and therefore SHA-512 is the only
-    ENABLED hash and is the default).
+    Existing projects are, by default, `converted', as described
+    above.
 
-    Newly minted server trees accept SHA-512.
+Y8: Clients hate SHA
+    Clients insist on trying to convert existing projects
+    It is very hard to stop this happening.
+    Unrepentant servers start being very hard to use.
 
+    Default configuration change
+       SHA deprecated (even in trees without working trees)
 
- start using SHA-512 by default.
+    Effects:
 
-Y6: Existing projects start being converted infectiously.
-    It is hard to stop this happening.
-    Old git software is firmly stuffed.
+    Clients will generate only BLAKE.  Hopefully their server will
+    accept this!
 
-    Default configuration change:
-       SHA-1 is OBSOLESCENT
-       (default for SHA-512, and HEAD hash, computed as in Y4)
+Y10: Stop accepting new SHA
+    No-one can manage to make new SHA commits
 
-    Result is that by default all software 
+    Default configuration change
+       SHA disabled in new trees, except during initial
+          `clone', `mirror' and similar
 
-    (Projects which do not want to convert need to set SHA-1 to
-    ENABLED, explicitly, on their 
-
-Y6: Existing projects start using SHA-512.
+    Effects:
 
-    Default configuration change:
-       SHA-512 is ENABLED
-       SHA-1 is OBSOLESCENT
-       (default default HEAD hash is already SHA-512)
+    Existing SHA history is retained, and copied to new clients and
+    servers.  But established clients and servers reject any newly
+    introduced SHA.
 
-      In existing repositories where no special action 
 
 
 --