Rev 4333: Docs for check. in http://people.ubuntu.com/~robertc/baz2.0/check

[Robert Collins]

At http://people.ubuntu.com/~robertc/baz2.0/check

------------------------------------------------------------
revno: 4333
revision-id: robertc at robertcollins.net-20090506054834-4zzevk11lk0a1b32
parent: pqm at pqm.ubuntu.com-20090505195559-0qmeyyua7e407sym
committer: Robert Collins <robertc at robertcollins.net>
branch nick: check
timestamp: Wed 2009-05-06 15:48:34 +1000
message:
  Docs for check.
=== added file 'doc/developers/check.txt'
--- a/doc/developers/check.txt	1970-01-01 00:00:00 +0000
+++ b/doc/developers/check.txt	2009-05-06 05:48:34 +0000
@@ -0,0 +1,62 @@
+Check Notes
+===========
+
+.. contents:: :local:
+
+Overview
+--------
+
+Check has multiple responsibilities:
+
+* Ensure that the data as recorded on disk is accessible intact and unaltered.
+* Ensure that a branch/repository/tree/whatever is ready for upgrade.
+* Look for and report on recorded-data issues where previous bzr's, or changing
+  situations have lead so some form of inconsistency.
+* Report sufficient information for a user to either fix the issue themselves
+  or report a bug that will hopefully be sufficiently detailed we can fix based
+  on the initial report.
+* Not scare users when run if everything is okey-dokey.
+
+Ideally one check invocation can do all these things.
+
+Repository
+----------
+
+Things that can go wrong:
+* Bit errors or alterations may occur in raw data.
+* Data that is referenced may be missing
+* There could be a lot of garbage in upload etc.
+* File graphs may be inconsistent with inventories and parents.
+
+Branch
+------
+
+Things that can go wrong:
+* Tag or tip revision ids may be missing from the repo.
+* The revno tip cache may be wrong.
+* Various urls could be problematic (not inaccessible, just invalid)
+* Stacked-on branch could be inaccessible.
+
+Tree
+----
+
+Things that can go wrong:
+* Bit errors in dirstate.
+* Corrupt or invalid shelves.
+* Corrupt dirstates written to disk.
+* Cached inventories might not match repository.
+
+Duplicate work
+--------------
+
+If we check every branch in a repo separately we will encounter duplicate
+effort in assessing things like missing tags/tips, revno cache etc.
+
+Outline of approach
+-------------------
+
+To check a repository, we scan for branches, open their trees and generate
+summary data. We then collect all the summary data in as compact a form as
+possible and do a detailed check on the repository, calling back out to branch
+and trees as we encounter the actual data that that tree/branch requires to
+perform its check.