~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/principles.txt

• browse files at revision 5418.4.7
• compare with another revision
• download diff
• download tarball
• view history from revision 5418.4.7

• reverse the comparison (5418.4.7 to 963)
• stop comparing with revision 963

Show diffs side-by-side

added

removed

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.

• Older »

Loggerhead is a web-based interface for Breezy
Version: 2.0.1