Rev 4891: (mbp) add "design principles" document in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

[Canonical.com Patch Queue Manager]

At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 4891 [merge]
revision-id: pqm at pqm.ubuntu.com-20091214065227-yx76sxslanytwp6r
parent: pqm at pqm.ubuntu.com-20091214060530-uk93cdya34wzxb0s
parent: mbp at sourcefrog.net-20091214060659-1ucv8hpnky0cbnaj
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Mon 2009-12-14 06:52:27 +0000
message:
  (mbp) add "design principles" document
added:
  doc/developers/principles.txt  principles.txt-20091210051924-glnv9z521rg59deg-1
modified:
  doc/developers/index.txt       index.txt-20070508041241-qznziunkg0nffhiw-1
=== modified file 'doc/developers/index.txt'
--- a/doc/developers/index.txt	2009-12-02 20:34:07 +0000
+++ b/doc/developers/index.txt	2009-12-14 06:06:59 +0000
@@ -46,6 +46,7 @@
 .. toctree::
    :maxdepth: 1
 
+   principles
    plans
    specifications
    implementation-notes

=== added file 'doc/developers/principles.txt'
--- a/doc/developers/principles.txt	1970-01-01 00:00:00 +0000
+++ b/doc/developers/principles.txt	2009-12-14 04:58:08 +0000
@@ -0,0 +1,62 @@
+========================
+Bazaar Design Principles
+========================
+
+We have learned or adopted a few general principles for code in Bazaar.
+Generally we will try to follow them in future, either for consistency or
+because they've been proven to work well, or both.  
+
+We may need to depart from these principles in particular special cases,
+or modify them as we learn more, or we might be diverging for them for no
+very good reason but just because of bugs.  If in doubt, ask.  
+
+See also: `Bazaar Developer Document Catalog <index.html>`_.
+
+
+Testing
+-------
+
+Untested code is broken code.
+
+So if a function is removed from the normal flow of execution (perhaps
+because a new default format was introduced) we have to make sure we can
+still execute and test the old code -- or remove it altogether.
+
+
+
+Data formats
+------------
+
+Fixing code once it's released is easy; fixing a problematic data format
+once people have started using it is more difficult.  We should document
+and review formats separately from the code that implements them.
+
+Data formats should have clear format markers that allow us to support new
+formats in future.  It should be easy to read the format without reading
+the whole object.
+
+The format marker should be a string understandable by a user that names
+the format and gives the bzr release that introduced it.  If the bzr
+program doesn't understand that format, it can at least show that format
+marker to the user.
+
+Once we mark a format as supported, we'll continue supporting it for
+several future releases, and support upgrading from it
+forever.
+
+Once we've released a format, we normally don't change it.  Adding new
+optional elements can cause problems when older clients don't understand
+those changes, or don't propagate them properly.
+
+We clearly distinguish internal files from user files.  Files inside
+``.bzr/`` are only written to by bzr and we discourage users from editing
+them.  Within bzr, code addressing the abstract interface of the Branch,
+BzrDir, etc shouldn't know where or how the internal files are stored.  If
+anything else is written in there, it won't be propagated when pushing or
+pulling, and won't be converted when upgrading.  (This is not quite true
+though; there is a ``branch.conf``.)
+
+User files within the tree, by contrast, we always store and return
+verbatim.  It's OK for Bazaar to read and act on these files (as we do
+with ``.bzrignore``), and to update them (as ``bzr ignore`` does), but
+they remain clearly user files and can be directly edited.