/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/developers/principles.txt

  • Committer: Xavier Maillard
  • Date: 2008-03-26 06:21:48 UTC
  • mto: (3322.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 3323.
  • Revision ID: xma@gnu.org-20080326062148-f7mnwvttv4oq8013
Add mail-mode GNU Emacs mail package as a mail_client option.
    
Idea and original code by Bojan Nikolic modified in this way:
    
1. define a different python class EmacsMailMode
2. use mail-mode package instead of message-mode. mail-mode is the
   default mail mode in GNU Emacs.
3. put the patch as a MIME attachment (see NOTE)
4. add tests as required to fulfil merge strategy requirements
    
To use this option, just put these lines into ~/.bazaar/bazaar.conf
    
[DEFAULT]
mail_client = emacs-mailmode

NOTE: this will work only for GNU Emacs version from 22.1 and superior.
      The MIME attachment is handled by etach[1] package. Just put
      etach.el into your `load-path'. GNU Emacs is not shipped with a
      simple MIME package thus the need of a simple and reliable
      alternative (etach does both reading and writing of MIME objects).

[1] http://rulnick.com/etach/download

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/principles.txt
1
 
========================
2
 
Bazaar Design Principles
3
 
========================
4
 
 
5
 
We have learned or adopted a few general principles for code in Bazaar.
6
 
Generally we will try to follow them in future, either for consistency or
7
 
because they've been proven to work well, or both.  
8
 
 
9
 
We may need to depart from these principles in particular special cases,
10
 
or modify them as we learn more, or we might be diverging for them for no
11
 
very good reason but just because of bugs.  If in doubt, ask.  
12
 
 
13
 
See also: `Bazaar Developer Document Catalog <index.html>`_.
14
 
 
15
 
 
16
 
Testing
17
 
-------
18
 
 
19
 
Untested code is broken code.
20
 
 
21
 
So if a function is removed from the normal flow of execution (perhaps
22
 
because a new default format was introduced) we have to make sure we can
23
 
still execute and test the old code -- or remove it altogether.
24
 
 
25
 
 
26
 
 
27
 
Data formats
28
 
------------
29
 
 
30
 
Fixing code once it's released is easy; fixing a problematic data format
31
 
once people have started using it is more difficult.  We should document
32
 
and review formats separately from the code that implements them.
33
 
 
34
 
Data formats should have clear format markers that allow us to support new
35
 
formats in future.  It should be easy to read the format without reading
36
 
the whole object.
37
 
 
38
 
The format marker should be a string understandable by a user that names
39
 
the format and gives the bzr release that introduced it.  If the bzr
40
 
program doesn't understand that format, it can at least show that format
41
 
marker to the user.
42
 
 
43
 
Once we mark a format as supported, we'll continue supporting it for
44
 
several future releases, and support upgrading from it
45
 
forever.
46
 
 
47
 
Once we've released a format, we normally don't change it.  Adding new
48
 
optional elements can cause problems when older clients don't understand
49
 
those changes, or don't propagate them properly.
50
 
 
51
 
We clearly distinguish internal files from user files.  Files inside
52
 
``.bzr/`` are only written to by bzr and we discourage users from editing
53
 
them.  Within bzr, code addressing the abstract interface of the Branch,
54
 
BzrDir, etc shouldn't know where or how the internal files are stored.  If
55
 
anything else is written in there, it won't be propagated when pushing or
56
 
pulling, and won't be converted when upgrading.  (This is not quite true
57
 
though; there is a ``branch.conf``.)
58
 
 
59
 
User files within the tree, by contrast, we always store and return
60
 
verbatim.  It's OK for Bazaar to read and act on these files (as we do
61
 
with ``.bzrignore``), and to update them (as ``bzr ignore`` does), but
62
 
they remain clearly user files and can be directly edited.