Rev 2477: HACKING in http://bzr.arbash-meinel.com/branches/bzr/bzr.dev
John Arbash Meinel
john at arbash-meinel.com
Wed May 2 16:34:38 BST 2007
At http://bzr.arbash-meinel.com/branches/bzr/bzr.dev
------------------------------------------------------------
revno: 2477
revision-id: john at arbash-meinel.com-20070502153435-66dyyx4gbe03juqq
parent: pqm at pqm.ubuntu.com-20070502125159-zpnij2o99tlddedp
parent: ian.clatworthy at internode.on.net-20070502044327-uvny1xwti20eh1p3
committer: John Arbash Meinel <john at arbash-meinel.com>
branch nick: bzr.dev
timestamp: Wed 2007-05-02 10:34:35 -0500
message:
HACKING
modified:
HACKING HACKING-20050805200004-2a5dc975d870f78c
------------------------------------------------------------
revno: 2466.6.3
merged: ian.clatworthy at internode.on.net-20070502044327-uvny1xwti20eh1p3
parent: ian.clatworthy at internode.on.net-20070430081033-2uer1v88nhaz4532
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.HACKING
timestamp: Wed 2007-05-02 14:43:27 +1000
message:
Incorporate feedback from Aaron B. & Alex B.
------------------------------------------------------------
revno: 2466.6.2
merged: ian.clatworthy at internode.on.net-20070430081033-2uer1v88nhaz4532
parent: ian.clatworthy at internode.on.net-20070427150319-tldij8hy0tcsij2q
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.HACKING
timestamp: Mon 2007-04-30 18:10:33 +1000
message:
Incorporate feedback from LarstiQ
------------------------------------------------------------
revno: 2466.6.1
merged: ian.clatworthy at internode.on.net-20070427150319-tldij8hy0tcsij2q
parent: pqm at pqm.ubuntu.com-20070426211103-h84prqh7a4ad3ez2
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.HACKING
timestamp: Sat 2007-04-28 01:03:19 +1000
message:
Expand HACKING into Bazaar Developer Guide
-------------- next part --------------
=== modified file 'HACKING'
--- a/HACKING 2007-04-24 14:19:24 +0000
+++ b/HACKING 2007-05-02 15:34:35 +0000
@@ -1,14 +1,225 @@
-============================
-Guidelines for modifying bzr
-============================
+======================
+Bazaar Developer Guide
+======================
.. contents::
(The current version of this document is available in the file ``HACKING``
-in the source tree, or at http://doc.bazaar-vcs.org/current/hacking.html)
-
-Overall
-=======
+in the source tree, or at http://doc.bazaar-vcs.org/bzr.dev/hacking.html)
+
+
+Getting Started
+###############
+
+Exploring the Bazaar Platform
+=============================
+
+Before making changes, it's a good idea to explore the work already
+done by others. Perhaps the new feature or improvement you're looking
+for is available in another plug-in already? If you find a bug,
+perhaps someone else has already fixed it?
+
+To answer these questions and more, take a moment to explore the
+overall Bazaar Platform. Here are some links to browse:
+
+* The Plugins page on the Wiki - http://bazaar-vcs.org/BzrPlugins
+
+* The Bazaar product family on Launchpad - https://launchpad.net/bazaar
+
+* Bug Tracker for the core product - https://bugs.launchpad.net/bzr/
+
+* Blueprint Tracker for the core product - https://blueprints.launchpad.net/bzr/
+
+If nothing else, perhaps you'll find inspiration in how other developers
+have solved their challenges.
+
+
+Planning and Discussing Changes
+===============================
+
+There is a very active community around Bazaar. Mostly we meet on IRC
+(#bzr on irc.freenode.net) and on the mailing list. To join the Bazaar
+community, see http://bazaar-vcs.org/BzrSupport.
+
+If you are planning to make a change, it's a very good idea to mention it
+on the IRC channel and/or on the mailing list. There are many advantages
+to involving the community before you spend much time on a change.
+These include:
+
+* you get to build on the wisdom on others, saving time
+
+* if others can direct you to similar code, it minimises the work to be done
+
+* it assists everyone in coordinating direction, priorities and effort.
+
+In summary, maximising the input from others typically minimises the
+total effort required to get your changes merged. The community is
+friendly, helpful and always keen to welcome newcomers.
+
+
+Bazaar Development in a Nutshell
+================================
+
+Looking for a 10 minute introduction to submitting a change?
+See http://bazaar-vcs.org/BzrGivingBack.
+
+TODO: Merge that Wiki page into this document.
+
+
+Understanding the Development Process
+=====================================
+
+The development team follows many best-practices including:
+
+* a public roadmap and planning process in which anyone can participate
+
+* time based milestones everyone can work towards and plan around
+
+* extensive code review and feedback to contributors
+
+* complete and rigorous test coverage on any code contributed
+
+* automated validation that all tests still pass before code is merged
+ into the main code branch.
+
+The key tools we use to enable these practices are:
+
+* Launchpad - https://launchpad.net/
+
+* Bazaar - http://bazaar-vcs.org/
+
+* Bundle Buggy - http://bundlebuggy.aaronbentley.com/
+
+* Patch Queue Manager - https://launchpad.net/pqm/
+
+For further information, see http://bazaar-vcs.org/BzrDevelopment.
+
+
+A Closer Look at the Merge & Review Process
+===========================================
+
+If you'd like to propose a change, please post to the
+bazaar at lists.canonical.com list with a bundle, patch, or link to a
+branch. Put '[PATCH]' or '[MERGE]' in the subject so Bundle Buggy
+can pick it out, and explain the change in the email message text.
+Remember to update the NEWS file as part of your change if it makes any
+changes visible to users or plugin developers. Please include a diff
+against mainline if you're giving a link to a branch.
+
+You can generate a bundle like this::
+
+ bzr bundle > mybundle.patch
+
+A .patch extension is recommended instead of .bundle as many mail clients
+will send the latter as a binary file. If a bundle would be too long or your
+mailer mangles whitespace (e.g. implicitly converts Unix newlines to DOS
+newlines), use the merge-directive command instead like this::
+
+ bzr merge-directive http://bazaar-vcs.org http://example.org/my_branch > my_directive.patch
+
+See the help for details on the arguments to merge-directive.
+
+Please do **NOT** put [PATCH] or [MERGE] in the subject line if you don't
+want it to be merged. If you want comments from developers rather than
+to be merged, you can put '[RFC]' in the subject line.
+
+Anyone is welcome to review code. There are broadly three gates for
+code to get in:
+
+ * Doesn't reduce test coverage: if it adds new methods or commands,
+ there should be tests for them. There is a good test framework
+ and plenty of examples to crib from, but if you are having trouble
+ working out how to test something feel free to post a draft patch
+ and ask for help.
+
+ * Doesn't reduce design clarity, such as by entangling objects
+ we're trying to separate. This is mostly something the more
+ experienced reviewers need to help check.
+
+ * Improves bugs, features, speed, or code simplicity.
+
+Code that goes in should pass all three. The core developers take care
+to keep the code quality high and understandable while recognising that
+perfect is sometimes the enemy of good. (It is easy for reviews to make
+people notice other things which should be fixed but those things should
+not hold up the original fix being accepted. New things can easily be
+recorded in the Bug Tracker instead.)
+
+Anyone can "vote" on the mailing list. Core developers can also vote using
+Bundle Buggy. Here are the voting codes and their explanations.
+
+ -1 really don't want it in current form
+ -0 somewhat uncomfortable
+ +0 comfortable but resubmission after changes requested
+ +1 conditional good to go after some minor changes
+ +1 good to go
+
++1 conditional is used as a way to avoid another submit/review cycle for
+patches that need small changes.
+
+If a change gets two +1 votes from core reviewers, and no
+vetos, then it's OK to come in. Any of the core developers can bring it
+into the bzr.dev trunk and backport it to maintenance branches if required.
+The Release Manager will merge the change into the branch for a pending
+release, if any. As a guideline, core developers usually merge their own
+changes and volunteer to merge other contributions if they were the second
+reviewer to agree to a change.
+
+To track the progress of proposed changes, use Bundle Buggy. See
+http://bundlebuggy.aaronbentley.com/help for a link to all the
+outstanding merge requests together with an explanation of the columns.
+Bundle Buggy will also mail you a link to track just your change.
+
+
+Preparing a Sandbox for Making Changes to Bazaar
+================================================
+
+Bazaar supports many ways of organising your work. See
+http://bazaar-vcs.org/SharedRepositoryLayouts for a summary of the
+popular alternatives.
+
+Of course, the best choice for you will depend on numerous factors:
+the number of changes you may be making, the complexity of the changes, etc.
+As a starting suggestion though:
+
+* create a local copy of the main development branch (bzr.dev) by using
+ this command: bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
+
+* keep your copy of bzr.dev prestine (by not developing in it) and keep
+ it up to date (by using bzr pull)
+
+* create a new branch off your local bzr.dev copy for each issue
+ (bug or feature) you are working on.
+
+This approach makes it easy to go back and make any required changes
+after a code review. Resubmitting the change is then simple with no
+risk of accidentially including edits related to other issues you may
+be working on. After the changes for an issue are accepted and merged,
+the associated branch can be deleted or archived as you wish.
+
+
+Navigating the Code Base
+========================
+
+TODO: List and describe in one line the purpose of each directory
+inside an installation of bzr.
+
+TODO: Refer to a central location holding an up to date copy of the API
+documentation generated by epydoc, e.g. something like
+http://starship.python.net/crew/mwh/bzrlibapi/bzrlib.html.
+
+
+Testing Bazaar
+##############
+
+The Importance of Testing
+=========================
+
+Reliability is a critical success factor for any Version Control System.
+We want Bazaar to be highly reliable across multiple platforms while
+evolving over time to meet the needs of its community.
+
+In a nutshell, this is want we expect and encourage:
* New functionality should have test cases. Preferably write the
test before writing the code.
@@ -16,37 +227,175 @@
In general, you can test at either the command-line level or the
internal API level. See Writing Tests below for more detail.
-* Try to practice Test-Driven Development. before fixing a bug, write a
+* Try to practice Test-Driven Development: before fixing a bug, write a
test case so that it does not regress. Similarly for adding a new
feature: write a test case for a small version of the new feature before
starting on the code itself. Check the test fails on the old code, then
add the feature or fix and check it passes.
-* Exceptions should be defined inside bzrlib.errors, so that we can
- see the whole tree at a glance.
-
-* Imports should be done at the top-level of the file, unless there is
- a strong reason to have them lazily loaded when a particular
- function runs. Import statements have a cost, so try to make sure
- they don't run inside hot functions.
-
-* Module names should always be given fully-qualified,
- i.e. ``bzrlib.hashcache`` not just ``hashcache``.
-
-* Commands should return non-zero when they encounter circumstances that
- the user should really pay attention to - which includes trivial shell
- pipelines.
-
- Recommended values are
- 0. OK,
- 1. Conflicts in merge-like operations, or changes are present in
- diff-like operations.
- 2. Unrepresentable diff changes (i.e. binary files that we cannot show
- a diff of).
- 3. An error or exception has occurred.
-
-Evolving interfaces
--------------------
+By doing these things, the Bazaar team gets increased confidence that
+changes do what they claim to do, whether provided by the core team or
+by community members. Equally importantly, we can be surer that changes
+down the track do not break new features or bug fixes that you are
+contributing today.
+
+As of May 2007, Bazaar ships with a test suite containing over 6000 tests
+and growing. We are proud of it and want to remain so. As community
+members, we all benefit from it. Would you trust version control on
+your project to a product *without* a test suite like Bazaar has?
+
+
+Running the Test Suite
+======================
+
+Currently, bzr selftest is used to invoke tests.
+You can provide a pattern argument to run a subset. For example,
+to run just the blackbox tests, run::
+
+ ./bzr selftest -v blackbox
+
+To skip a particular test (or set of tests), use the --exclude option
+(shorthand -x) like so::
+
+ ./bzr selftest -v -x blackbox
+
+To list tests without running them, use the --list-only option like so::
+
+ ./bzr selftest --list-only
+
+This option can be combined with other selftest options (like -x) and
+filter patterns to understand their effect.
+
+
+Writing Tests
+=============
+
+In general tests should be placed in a file named test_FOO.py where
+FOO is the logical thing under test. That file should be placed in the
+tests subdirectory under the package being tested.
+
+For example, tests for merge3 in bzrlib belong in bzrlib/tests/test_merge3.py.
+See bzrlib/tests/test_sampler.py for a template test script.
+
+Tests can be written for the UI or for individual areas of the library.
+Choose whichever is appropriate: if adding a new command, or a new command
+option, then you should be writing a UI test. If you are both adding UI
+functionality and library functionality, you will want to write tests for
+both the UI and the core behaviours. We call UI tests 'blackbox' tests
+and they are found in ``bzrlib/tests/blackbox/*.py``.
+
+When writing blackbox tests please honour the following conventions:
+
+ 1. Place the tests for the command 'name' in
+ bzrlib/tests/blackbox/test_name.py. This makes it easy for developers
+ to locate the test script for a faulty command.
+
+ 2. Use the 'self.run_bzr("name")' utility function to invoke the command
+ rather than running bzr in a subprocess or invoking the
+ cmd_object.run() method directly. This is a lot faster than
+ subprocesses and generates the same logging output as running it in a
+ subprocess (which invoking the method directly does not).
+
+ 3. Only test the one command in a single test script. Use the bzrlib
+ library when setting up tests and when evaluating the side-effects of
+ the command. We do this so that the library api has continual pressure
+ on it to be as functional as the command line in a simple manner, and
+ to isolate knock-on effects throughout the blackbox test suite when a
+ command changes its name or signature. Ideally only the tests for a
+ given command are affected when a given command is changed.
+
+ 4. If you have a test which does actually require running bzr in a
+ subprocess you can use ``run_bzr_subprocess``. By default the spawned
+ process will not load plugins unless ``--allow-plugins`` is supplied.
+
+
+Doctests
+--------
+
+We make selective use of doctests__. In general they should provide
+*examples* within the API documentation which can incidentally be tested. We
+don't try to test every important case using doctests -- regular Python
+tests are generally a better solution.
+
+Most of these are in ``bzrlib/doc/api``. More additions are welcome.
+
+ __ http://docs.python.org/lib/module-doctest.html
+
+
+Essential Domain Classes
+########################
+
+Introducing the Object Model
+============================
+
+The core domain objects within the bazaar model are:
+
+* Transport
+
+* Branch
+
+* Repository
+
+* WorkingTree
+
+Transports are explained below. See http://bazaar-vcs.org/Classes/
+for an introduction to the other key classes.
+
+Using Transports
+================
+
+The ``Transport`` layer handles access to local or remote directories.
+Each Transport object acts like a logical connection to a particular
+directory, and it allows various operations on files within it. You can
+*clone* a transport to get a new Transport connected to a subdirectory or
+parent directory.
+
+Transports are not used for access to the working tree. At present
+working trees are always local and they are accessed through the regular
+Python file io mechanisms.
+
+Filenames vs URLs
+-----------------
+
+Transports work in URLs. Take note that URLs are by definition only
+ASCII - the decision of how to encode a Unicode string into a URL must be
+taken at a higher level, typically in the Store. (Note that Stores also
+escape filenames which cannot be safely stored on all filesystems, but
+this is a different level.)
+
+The main reason for this is that it's not possible to safely roundtrip a
+URL into Unicode and then back into the same URL. The URL standard
+gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
+doesn't say how those bytes represent non-ASCII characters. (They're not
+guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
+
+For example if the user enters the url ``http://example/%e0`` there's no
+way to tell whether that character represents "latin small letter a with
+grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2
+or malformed UTF-8. So we can't convert their URL to Unicode reliably.
+
+Equally problematic if we're given a url-like string containing non-ascii
+characters (such as the accented a) we can't be sure how to convert that
+to the correct URL, because we don't know what encoding the server expects
+for those characters. (Although this is not totally reliable we might still
+accept these and assume they should be put into UTF-8.)
+
+A similar edge case is that the url ``http://foo/sweet%2Fsour`` contains
+one directory component whose name is "sweet/sour". The escaped slash is
+not a directory separator. If we try to convert URLs to regular Unicode
+paths this information will be lost.
+
+This implies that Transports must natively deal with URLs; for simplicity
+they *only* deal with URLs and conversion of other strings to URLs is done
+elsewhere. Information they return, such as from ``list_dir``, is also in
+the form of URL components.
+
+
+Core Topics
+###########
+
+Evolving Interfaces
+===================
We have a commitment to 6 months API stability - any supported symbol in a
release of bzr MUST NOT be altered in any way that would result in
@@ -72,128 +421,8 @@
callers will at least get an AttributeError rather than weird results.
-Standard parameter types
-------------------------
-
-There are some common requirements in the library: some parameters need to be
-unicode safe, some need byte strings, and so on. At the moment we have
-only codified one specific pattern: Parameters that need to be unicode
-should be checked via ``bzrlib.osutils.safe_unicode``. This will coerce the
-input into unicode in a consistent fashion, allowing trivial strings to be
-used for programmer convenience, but not performing unpredictably in the
-presence of different locales.
-
-
-Copyright
----------
-
-The copyright policy for bzr was recently made clear in this email (edited
-for grammatical correctness)::
-
- The attached patch cleans up the copyright and license statements in
- the bzr source. It also adds tests to help us remember to add them
- with the correct text.
-
- We had the problem that lots of our files were "Copyright Canonical
- Development Ltd" which is not a real company, and some other variations
- on this theme. Also, some files were missing the GPL statements.
-
- I want to be clear about the intent of this patch, since copyright can
- be a little controversial.
-
- 1) The big motivation for this is not to shut out the community, but
- just to clean up all of the invalid copyright statements.
-
- 2) It has been the general policy for bzr that we want a single
- copyright holder for all of the core code. This is following the model
- set by the FSF, which makes it easier to update the code to a new
- license in case problems are encountered. (For example, if we want to
- upgrade the project universally to GPL v3 it is much simpler if there is
- a single copyright holder). It also makes it clearer if copyright is
- ever debated, there is a single holder, which makes it easier to defend
- in court, etc. (I think the FSF position is that if you assign them
- copyright, they can defend it in court rather than you needing to, and
- I'm sure Canonical would do the same).
- As such, Canonical has requested copyright assignments from all of the
- major contributers.
-
- 3) If someone wants to add code and not attribute it to Canonical, there
- is a specific list of files that are excluded from this check. And the
- test failure indicates where that is, and how to update it.
-
- 4) If anyone feels that I changed a copyright statement incorrectly, just
- let me know, and I'll be happy to correct it. Whenever you have large
- mechanical changes like this, it is possible to make some mistakes.
-
- Just to reiterate, this is a community project, and it is meant to stay
- that way. Core bzr code is copyright Canonical for legal reasons, and
- the tests are just there to help us maintain that.
-
-
-Documentation
-=============
-
-When you change bzrlib, please update the relevant documentation for the
-change you made: Changes to commands should update their help, and
-possibly end user tutorials; changes to the core library should be
-reflected in API documentation.
-
-Commands
---------
-
-The docstring of a command is used by ``bzr help`` to generate help output
-for the command. The list 'takes_options' attribute on a command is used by
-``bzr help`` to document the options for the command - the command
-docstring does not need to document them. Finally, the '_see_also'
-attribute on a command can be used to reference other related help topics.
-
-NEWS file
----------
-
-If you make a user-visible change, please add a note to the NEWS file.
-The description should be written to make sense to someone who's just
-a user of bzr, not a developer: new functions or classes shouldn't be
-mentioned, but new commands, changes in behaviour or fixed nontrivial
-bugs should be listed. See the existing entries for an idea of what
-should be done.
-
-Within each release, entries in the news file should have the most
-user-visible changes first. So the order should be approximately:
-
- * changes to existing behaviour - the highest priority because the
- user's existing knowledge is incorrect
- * new features - should be brought to their attention
- * bug fixes - may be of interest if the bug was affecting them, and
- should include the bug number if any
- * major documentation changes
- * changes to internal interfaces
-
-People who made significant contributions to each change are listed in
-parenthesis. This can include reporting bugs (particularly with good
-details or reproduction recipes), submitting patches, etc.
-
-API documentation
------------------
-
-Functions, methods, classes and modules should have docstrings
-describing how they are used.
-
-The first line of the docstring should be a self-contained sentence.
-
-For the special case of Command classes, this acts as the user-visible
-documentation shown by the help command.
-
-The docstrings should be formatted as reStructuredText_ (like this
-document), suitable for processing using the epydoc_ tool into HTML
-documentation.
-
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
-.. _epydoc: http://epydoc.sourceforge.net/
-
-
-
-Coding style
-============
+Coding Style Guidelines
+=======================
Please write PEP-8__ compliant code.
@@ -203,6 +432,17 @@
__ http://www.python.org/peps/pep-0008.html
+Module Imports
+--------------
+
+* Imports should be done at the top-level of the file, unless there is
+ a strong reason to have them lazily loaded when a particular
+ function runs. Import statements have a cost, so try to make sure
+ they don't run inside hot functions.
+
+* Module names should always be given fully-qualified,
+ i.e. ``bzrlib.hashcache`` not just ``hashcache``.
+
Naming
------
@@ -224,7 +464,7 @@
inconsistency if other people use the full name.
-Standard names
+Standard Names
--------------
``revision_id`` not ``rev_id`` or ``revid``
@@ -331,7 +571,7 @@
object, rather than the real class.
-Passing to other variables
+Passing to Other Variables
~~~~~~~~~~~~~~~~~~~~~~~~~~
It also is incorrect to assign ``ImportReplacer`` objects to other variables.
@@ -342,7 +582,30 @@
variable, so some bugs are not detected right away.
-Writing output
+Getting Input
+=============
+
+Processing Command Lines
+------------------------
+
+bzrlib has a standard framework for parsing command lines and calling
+processing routines associated with various commands. See builtins.py
+for numerous examples.
+
+
+Standard Parameter Types
+------------------------
+
+There are some common requirements in the library: some parameters need to be
+unicode safe, some need byte strings, and so on. At the moment we have
+only codified one specific pattern: Parameters that need to be unicode
+should be checked via ``bzrlib.osutils.safe_unicode``. This will coerce the
+input into unicode in a consistent fashion, allowing trivial strings to be
+used for programmer convenience, but not performing unpredictably in the
+presence of different locales.
+
+
+Writing Output
==============
(The strategy described here is what we want to get to, but it's not
@@ -379,86 +642,24 @@
should be only in the command-line tool.
-Writing tests
-=============
-
-In general tests should be placed in a file named test_FOO.py where
-FOO is the logical thing under test. That file should be placed in the
-tests subdirectory under the package being tested.
-
-For example, tests for merge3 in bzrlib belong in bzrlib/tests/test_merge3.py.
-See bzrlib/tests/test_sampler.py for a template test script.
-
-Tests can be written for the UI or for individual areas of the library.
-Choose whichever is appropriate: if adding a new command, or a new command
-option, then you should be writing a UI test. If you are both adding UI
-functionality and library functionality, you will want to write tests for
-both the UI and the core behaviours. We call UI tests 'blackbox' tests
-and they are found in ``bzrlib/tests/blackbox/*.py``.
-
-When writing blackbox tests please honour the following conventions:
-
- 1. Place the tests for the command 'name' in
- bzrlib/tests/blackbox/test_name.py. This makes it easy for developers
- to locate the test script for a faulty command.
-
- 2. Use the 'self.run_bzr("name")' utility function to invoke the command
- rather than running bzr in a subprocess or invoking the
- cmd_object.run() method directly. This is a lot faster than
- subprocesses and generates the same logging output as running it in a
- subprocess (which invoking the method directly does not).
-
- 3. Only test the one command in a single test script. Use the bzrlib
- library when setting up tests and when evaluating the side-effects of
- the command. We do this so that the library api has continual pressure
- on it to be as functional as the command line in a simple manner, and
- to isolate knock-on effects throughout the blackbox test suite when a
- command changes its name or signature. Ideally only the tests for a
- given command are affected when a given command is changed.
-
- 4. If you have a test which does actually require running bzr in a
- subprocess you can use ``run_bzr_subprocess``. By default the spawned
- process will not load plugins unless ``--allow-plugins`` is supplied.
-
-
-Doctests
---------
-
-We make selective use of doctests__. In general they should provide
-*examples* within the API documentation which can incidentally be tested. We
-don't try to test every important case using doctests -- regular Python
-tests are generally a better solution.
-
-Most of these are in ``bzrlib/doc/api``. More additions are welcome.
-
- __ http://docs.python.org/lib/module-doctest.html
-
-
-Running tests
-=============
-Currently, bzr selftest is used to invoke tests.
-You can provide a pattern argument to run a subset. For example,
-to run just the blackbox tests, run::
-
- ./bzr selftest -v blackbox
-
-To skip a particular test (or set of tests), use the --exclude option
-(shorthand -x) like so::
-
- ./bzr selftest -v -x blackbox
-
-To list tests without running them, use the --list-only option like so::
-
- ./bzr selftest --list-only
-
-This option can be combined with other selftest options (like -x) and
-filter patterns to understand their effect.
-
-
-Errors and exceptions
-=====================
-
-Errors are handled through Python exceptions.
+Handling Errors and Exceptions
+==============================
+
+Commands should return non-zero when they encounter circumstances that
+the user should really pay attention to - which includes trivial shell
+pipelines.
+
+Recommended values are:
+
+ 0. OK.
+ 1. Conflicts in merge-like operations, or changes are present in
+ diff-like operations.
+ 2. Unrepresentable diff changes (i.e. binary files that we cannot show
+ a diff of).
+ 3. An error or exception has occurred.
+
+Errors are handled through Python exceptions. Exceptions should be defined
+inside bzrlib.errors, so that we can see the whole tree at a glance.
We broadly classify errors as either being either internal or not,
depending on whether ``user_error`` is set or not. If we think it's our
@@ -492,6 +693,118 @@
final fullstop. If long, they may contain newlines to break the text.
+Documenting Changes
+===================
+
+When you change bzrlib, please update the relevant documentation for the
+change you made: Changes to commands should update their help, and
+possibly end user tutorials; changes to the core library should be
+reflected in API documentation.
+
+NEWS File
+---------
+
+If you make a user-visible change, please add a note to the NEWS file.
+The description should be written to make sense to someone who's just
+a user of bzr, not a developer: new functions or classes shouldn't be
+mentioned, but new commands, changes in behaviour or fixed nontrivial
+bugs should be listed. See the existing entries for an idea of what
+should be done.
+
+Within each release, entries in the news file should have the most
+user-visible changes first. So the order should be approximately:
+
+ * changes to existing behaviour - the highest priority because the
+ user's existing knowledge is incorrect
+ * new features - should be brought to their attention
+ * bug fixes - may be of interest if the bug was affecting them, and
+ should include the bug number if any
+ * major documentation changes
+ * changes to internal interfaces
+
+People who made significant contributions to each change are listed in
+parenthesis. This can include reporting bugs (particularly with good
+details or reproduction recipes), submitting patches, etc.
+
+Commands
+--------
+
+The docstring of a command is used by ``bzr help`` to generate help output
+for the command. The list 'takes_options' attribute on a command is used by
+``bzr help`` to document the options for the command - the command
+docstring does not need to document them. Finally, the '_see_also'
+attribute on a command can be used to reference other related help topics.
+
+API Documentation
+-----------------
+
+Functions, methods, classes and modules should have docstrings
+describing how they are used.
+
+The first line of the docstring should be a self-contained sentence.
+
+For the special case of Command classes, this acts as the user-visible
+documentation shown by the help command.
+
+The docstrings should be formatted as reStructuredText_ (like this
+document), suitable for processing using the epydoc_ tool into HTML
+documentation.
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _epydoc: http://epydoc.sourceforge.net/
+
+
+General Guidelines
+==================
+
+Copyright
+---------
+
+The copyright policy for bzr was recently made clear in this email (edited
+for grammatical correctness)::
+
+ The attached patch cleans up the copyright and license statements in
+ the bzr source. It also adds tests to help us remember to add them
+ with the correct text.
+
+ We had the problem that lots of our files were "Copyright Canonical
+ Development Ltd" which is not a real company, and some other variations
+ on this theme. Also, some files were missing the GPL statements.
+
+ I want to be clear about the intent of this patch, since copyright can
+ be a little controversial.
+
+ 1) The big motivation for this is not to shut out the community, but
+ just to clean up all of the invalid copyright statements.
+
+ 2) It has been the general policy for bzr that we want a single
+ copyright holder for all of the core code. This is following the model
+ set by the FSF, which makes it easier to update the code to a new
+ license in case problems are encountered. (For example, if we want to
+ upgrade the project universally to GPL v3 it is much simpler if there is
+ a single copyright holder). It also makes it clearer if copyright is
+ ever debated, there is a single holder, which makes it easier to defend
+ in court, etc. (I think the FSF position is that if you assign them
+ copyright, they can defend it in court rather than you needing to, and
+ I'm sure Canonical would do the same).
+ As such, Canonical has requested copyright assignments from all of the
+ major contributers.
+
+ 3) If someone wants to add code and not attribute it to Canonical, there
+ is a specific list of files that are excluded from this check. And the
+ test failure indicates where that is, and how to update it.
+
+ 4) If anyone feels that I changed a copyright statement incorrectly, just
+ let me know, and I'll be happy to correct it. Whenever you have large
+ mechanical changes like this, it is possible to make some mistakes.
+
+ Just to reiterate, this is a community project, and it is meant to stay
+ that way. Core bzr code is copyright Canonical for legal reasons, and
+ the tests are just there to help us maintain that.
+
+
+Miscellaneous Topics
+####################
Debugging
=========
@@ -505,11 +818,10 @@
then bzr will go into pdb post-mortem mode when an unhandled exception
occurs.
-If you send a SIGQUIT signal to bzr, which can be done by pressing C-\ on Unix,
-bzr will go into the debugger immediately. You can continue execution by
-typing ``c``. This can be disabled if necessary by setting the
-environment variable ``BZR_SIGQUIT_PDB=0``.
-
+If you send a SIGQUIT signal to bzr, which can be done by pressing
+Ctrl-\\ on Unix, bzr will go into the debugger immediately. You can
+continue execution by typing ``c``. This can be disabled if necessary
+by setting the environment variable ``BZR_SIGQUIT_PDB=0``.
Jargon
@@ -521,56 +833,6 @@
indexes into the branch's revision history.
-Transport
-=========
-
-The ``Transport`` layer handles access to local or remote directories.
-Each Transport object acts like a logical connection to a particular
-directory, and it allows various operations on files within it. You can
-*clone* a transport to get a new Transport connected to a subdirectory or
-parent directory.
-
-Transports are not used for access to the working tree. At present
-working trees are always local and they are accessed through the regular
-Python file io mechanisms.
-
-filenames vs URLs
------------------
-
-Transports work in URLs. Take note that URLs are by definition only
-ASCII - the decision of how to encode a Unicode string into a URL must be
-taken at a higher level, typically in the Store. (Note that Stores also
-escape filenames which cannot be safely stored on all filesystems, but
-this is a different level.)
-
-The main reason for this is that it's not possible to safely roundtrip a
-URL into Unicode and then back into the same URL. The URL standard
-gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
-doesn't say how those bytes represent non-ASCII characters. (They're not
-guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
-
-For example if the user enters the url ``http://example/%e0`` there's no
-way to tell whether that character represents "latin small letter a with
-grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2
-or malformed UTF-8. So we can't convert their URL to Unicode reliably.
-
-Equally problematic if we're given a url-like string containing non-ascii
-characters (such as the accented a) we can't be sure how to convert that
-to the correct URL, because we don't know what encoding the server expects
-for those characters. (Although this is not totally reliable we might still
-accept these and assume they should be put into UTF-8.)
-
-A similar edge case is that the url ``http://foo/sweet%2Fsour`` contains
-one directory component whose name is "sweet/sour". The escaped slash is
-not a directory separator. If we try to convert URLs to regular Unicode
-paths this information will be lost.
-
-This implies that Transports must natively deal with URLs; for simplicity
-they *only* deal with URLs and conversion of other strings to URLs is done
-elsewhere. Information they return, such as from ``list_dir``, is also in
-the form of URL components.
-
-
Unicode and Encoding Support
============================
@@ -637,49 +899,6 @@
Use ``bzrlib.osutils.rmtree`` instead.
-Merge/review process
-====================
-
-If you'd like to propose a change, please post to the
-bazaar at lists.canonical.com list with a patch, bzr changeset, or link to a
-branch. Please put '[patch]' in the subject so we can pick them out, and
-include some text explaining the change. Remember to put an update to the NEWS
-file in your diff, if it makes any changes visible to users or plugin
-developers. Please include a diff against mainline if you're giving a link to
-a branch.
-
-Please indicate if you think the code is ready to merge, or if it's just a
-draft or for discussion. If you want comments from many developers rather than
-to be merged, you can put '[rfc]' in the subject lines.
-
-Anyone is welcome to review code. There are broadly three gates for
-code to get in:
-
- * Doesn't reduce test coverage: if it adds new methods or commands,
- there should be tests for them. There is a good test framework
- and plenty of examples to crib from, but if you are having trouble
- working out how to test something feel free to post a draft patch
- and ask for help.
-
- * Doesn't reduce design clarity, such as by entangling objects
- we're trying to separate. This is mostly something the more
- experienced reviewers need to help check.
-
- * Improves bugs, features, speed, or code simplicity.
-
-Code that goes in should pass all three.
-
-If you read a patch please reply and say so. We can use a numeric scale
-of -1, -0, +0, +1, meaning respectively "really don't want it in current
-form", "somewhat uncomfortable", "ok with me", and "please put it in".
-Anyone can "vote". (It's not really voting, just a terse expression.)
-
-If something gets say two +1 votes from core reviewers, and no
-vetos, then it's OK to come in. Any of the core developers can bring it
-into their integration branch, which I'll merge regularly. (If you do
-so, please reply and say so.)
-
-
C Extension Modules
===================
@@ -718,7 +937,8 @@
maintaining the python code twice - once in the .pyx, and once in the .py,
and no longer including the .py file.
-Making installers for OS Windows
+
+Making Installers for OS Windows
================================
To build a win32 installer, see the instructions on the wiki page:
http://bazaar-vcs.org/BzrWin32Installer
More information about the bazaar-commits
mailing list