wip

diff --git a/notes b/notes
index 8962089b614b54d0e3e94084888c56fba557654b..4e62252fa9e95259ece3eda5f2ca2c6ce75d089a 100644 (file)
--- a/notes
+++ b/notes
@@ -1,41 +1,89 @@
-PITCH
+-- PITCH --
+
+[archive as vcs]
+
+The Debian archive is a version control system.
+
+  Clone (checkout) <=> apt-get source
+  Commit+push <=> upload
+
+But:
+
+  No sensible branching
+  history browsing is appalling 
+  Terrible interaction with other VCSs
+
+Solution
+
+  Well, we might replace it.  But the archive is various other things
+  besides an appallingly bad VCS.  So instead, let's build something
+  to deal with the problems.
+
+  What that really means is that we need a better gateway.
 
 [manpage]
 
-uniform operation
+dgit is a tool which lets you treat the archive as if it were a git
+server.
+
+It provides uniform operation for all packages:
+
+You can clone any package, work on it, build it, and upload it.
+
+You don't need to know maintainer's workflow.  It doesn't matter
+whether the maintainer uses dgit, other git tools, quilt, CVS or SCCS.
+
+With dgit you do all direct source code management in git.  As a dgit
+user you do not interact with the archive directly.
+
+dgit is particularly useful for NMUers: you can prepare an RC bugfix,
+with full support from git, withut needing to know anything about the
+package's usual VCS arrangements.
+
+[demo]
 
-interacts with archive, not just with out-of-archive git trees
+dgit also has great potential for downstreams - that is, derivatives
+and users who want to modify a package.  Having used dgit clone or
+fetch, you can merge into your downstream branch.  (There are some
+issues with this right now for non-DDs, which I'm going to discuss
+later.)
 
-NMUer, derivatives
-  clone any package, work on it, and upload, all in git
-  no need to know maintainer's workflow
+As a maintainer you can choose, if you like, to use the dgit git
+history as your primary working history.  Any fast forwarding
+patches-applied git workflow works with dgit.  In particular, you can
+have the full upstream git history in the ancestry if your dgit git
+history.
 
-for maintainer
-  any fast forwarding patches-applied git workflow
-  full upstream git history in our git history
 
-demo
+-- PRINCIPLES OF OPERATION --
 
+[ .dsc, dpkg-source -x, git checkout, identity ]
 
-PRINCIPLES OF OPERATION
+This is Debian so you want to know how it works.  So let me run
+through dgit's principles of operation.  The data model is as follows:
 
-  data model
+A dgit-generated upload's .dsc contains a git commit hash.
+This specifies a commit whose tree is identical to the results of
+dpkg-source -x on the .dsc.
 
-    .dsc contains git hash
+But the actual git history is not stored in the archive.  It is
+obtained via the git protocol from an actual git server.  (Currently
+this is on alioth but it's going to move.)
 
-    git hash specifies a commit whose tree is identical to the
-      results of dpkg-source -x
+The only other constraint on the git commit named in the .dsc is that
+the successive dgit uploads must have a fast-forwarding history.
+Specifically, each upload made with dgit must have as an ancestor the
+current state of that package in the archive.
 
-    actual git data obtained from git server via git protool, not
-      from the archive
+[ synthetic commit example ]
 
-  fetch
+Non-dgit uploads do not contain a (suitable) git commit hash.  But
+dgit clone needs to produce a suitable git commit.  It does this by
+inventing (in a deterministic way) a commit corresponding to the state
+of the archive.  If necessary, it also generates a synthetic merge
+commit to tie the invented commit into the previous dgit history.
 
-    1. get .dsc information from archive
-    2. get previous dgit git history from git server
-    3. if necessary, synthesise a commit to represent non-dgit upload
 
-  push
 
     user has done build already (need for this may go away with
       source-only uploads)
@@ -70,3 +118,4 @@ ACCESS PROBLEMS
       need to abandon alioth because of collab-maint security issues
 
 
+xxx adoption