Rev 2486: add analysis in file:///home/robertc/source/baz/roadmap/

[Robert Collins]

At file:///home/robertc/source/baz/roadmap/

------------------------------------------------------------
revno: 2486
revision-id: robertc at robertcollins.net-20070515094946-9nrohtlybz2i5jt9
parent: pqm at pqm.ubuntu.com-20070510055501-w262sk5hl33vmd19
committer: Robert Collins <robertc at robertcollins.net>
branch nick: roadmap
timestamp: Tue 2007-05-15 19:49:46 +1000
message:
  add analysis
added:
  doc/developers/add.txt         add.txt-20070515094933-xhgz3xjc7o0edok0-2
=== added file 'doc/developers/add.txt'
--- a/doc/developers/add.txt	1970-01-01 00:00:00 +0000
+++ b/doc/developers/add.txt	2007-05-15 09:49:46 +0000
@@ -0,0 +1,34 @@
+Add
+---
+
+Add is used to recursively version some paths supplied by the user. Paths that
+match ignore rules are not versioned, and paths that become versioned are
+versioned in the nearest containing bzr tree. Currently we only do this within
+a single tree, but perhaps with nested trees this should change.
+
+Least work we can hope to perform
+=================================
+
+* Read a subset of the full versioned paths data for the tree matching the scope of the paths the user supplied.
+* Seek once to each directory within the scope and readdir its contents.
+* Probe if each directory is a child tree to avoid adding data for paths within a child tree.
+* Calculate the ignored status for paths not previously known to be ignored
+* Write data proportional to the newly versioned file count to record their versioning.
+* Assign a fileid for each path (so that merge --uncommitted can work immediately)
+
+Optionally:
+
+* Print the ignore rule for each ignored path in the scope.
+* Print the path of each added file.
+* Print the total count of ignored files within the scopes.
+* Record the result of calculating ignored status for ignored files.
+  (proportional to the number we actually calculate).
+
+Per file algorithm
+==================
+
+1. If the path is versioned, and it is a directory, push onto the recurse stack.
+1. If the path is supplied by the user or is not ignored, version it, and if a
+   directory, push onto the recurse stack. Versioning the path may require
+   versioning the paths parents.
+1. Output or otherwise record the ignored rule as per the user interface selected.