Rev 5054: (mbp) better tips for contribution in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Tue Feb 23 03:05:27 GMT 2010
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 5054 [merge]
revision-id: pqm at pqm.ubuntu.com-20100223030525-hbayninag92of8hi
parent: pqm at pqm.ubuntu.com-20100222201253-5awzw17i8w1dc9gp
parent: mbp at sourcefrog.net-20100223023252-zk4ds0sbeuga82et
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Tue 2010-02-23 03:05:25 +0000
message:
(mbp) better tips for contribution
modified:
doc/developers/contribution-quickstart.txt contributionquicksta-20091118014608-u0t1h53l2t81rir3-1
=== modified file 'doc/developers/contribution-quickstart.txt'
--- a/doc/developers/contribution-quickstart.txt 2010-02-19 04:00:31 +0000
+++ b/doc/developers/contribution-quickstart.txt 2010-02-23 02:32:52 +0000
@@ -1,62 +1,120 @@
-Bazaar Contribution in Five Minutes
-===================================
-
-Contributing to Bazaar requires attention to quality. To ensure
-high-quality commits, the "Bazaar process" involves you in our
-code review and improvement activities.
-
-In brief, a contribution should include:
-
-1. A brief rationale, including expected audience and use cases,
- for inclusion in Bazaar.
-
-2. A branch registered as a branch on Launchpad, and submitted as
- a merge proposal.
-
-3. The branch should include:
-
- a. implementation of the feature,
-
- b. user documentation (if the feature is visible in the user
- interface) and/or developer documentation (if new or
- changed APIs are provided), and
-
- c. tests to ensure the specification is correctly
- implemented.
-
-For more information, see the `Bazaar Developer Guide <HACKING.html>`_.
-
-If you are not an experienced Bazaar contributor, why not ask for
-mentoring? When you submit your merge proposal on Launchpad, simply say
-"I'd like to be mentored, please" in your submission. Or ask for help
-with your contribution on the IRC channel, mailing list, or on Launchpad
-(https://answers.launchpad.net/bzr).
-
-* `Giving back <http://wiki.bazaar.canonical.com/BzrGivingBack>`_: How to get
- your changes to Bazaar integrated into a release.
-
-
-Current Bazaar Mentors
-----------------------
-
-See the roster at http://bazaar-vcs.org/PatchPilot, although other
-developers may help too!
-
-
-Bazaar Mentors FAQ
-------------------
-
-1. Why is this "Bazaar process" in HACKING.txt so complicated?
-
- Answer: If we knew *that*, we'd simplify it! We are working
- on streamlining many aspects, but quality comes first.
-
-1. What sort of things can a mentor help with?
-
- Anything that's getting in your way, time permitting. This includes
- guiding you through the ``bzrlib`` API, explaining how to use our test
- infrastructure, discussing possible designs for your bug fix or
- feature, and so on.
+Contributing to Bazaar
+======================
+
+Talk to us
+----------
+
+If you want to fix or improve something in Bazaar, we want to help you.
+You can ask at any time for help, on the list, on irc, or through a merge
+proposal on Launchpad.
+
+In particular, the rostered
+`Patch Pilot <http://wiki.bazaar.canonical.com/PatchPilot>`_
+is an experienced developer who will help you get your changes in, through
+code review, advice, debugging, writing tests, or whatever it takes.
+
+* `Bazaar mailing list <http://lists.ubuntu.com/mailman/listinfo/bazaar>`_
+
+* IRC in channel ``#bzr`` on ``irc.ubuntu.com``
+
+
+Starting
+--------
+
+Before starting on a change it's a good idea to either file a bug, find a
+relevant existing bug, or send a proposal to the list. If there is a bug
+you should set it to "In Progress" and if you wish assign it to yourself.
+
+You might like to start with a bug tagged `easy
+<https://bugs.edge.launchpad.net/bzr/+bugs?field.tag=easy>`_.
+
+Making a branch
+---------------
+
+First, get a local copy of Bazaar::
+
+ $ cd $HOME
+ $ bzr init-repo bzr
+ $ cd bzr
+ $ bzr branch lp:bzr bzr.dev
+
+Now make your own branch; we recommend you include the bug number and also
+a brief description::
+
+ $ bzr branch bzr.dev 123456-status-speed
+
+and go ahead and commit in there. Normally you should fix only one bug or
+closely-related cluster of bugs per branch, to make reviews and merges
+flow more smoothly.
+
+For bugs that exist in older supported branches of bzr like 2.0 or 2.1,
+you might want to fix the bug there so it can go into a bugfix release,
+ie ::
+
+ $ bzr branch lp:bzr/2.1 bzr.2.1
+ $ bzr branch bzr.2.1 123458-2.1-status
+
+You probably want this configuration in ``~/.bazaar/locations.conf``::
+
+ [/home/USER/bzr]
+ push_location = lp:~LAUNCHPAD_USER/bzr/
+ push_location:policy = appendpath
+ public_branch = http://bazaar.launchpad.net/~LAUNCHPAD_USER/bzr/
+ public_branch:policy = appendpath
+
+with your local and Launchpad usernames inserted.
+
+
+Writing tests
+-------------
+
+We value test coverage and generally all changes should have or update a
+test. There is a powerful test framework but it can be hard to find the
+right place to put your test. Don't hesitate to ask, or to propose a
+merge that does not yet have tests.
+
+Normally for command-line code you should look in
+``bzrlib.tests.blackbox`` and for library code in ``bzrlib.tests``. For
+functions on an interface for which there are multiple implementations,
+like `Transport`, look in ``bzrlib.tests.per_transport``.
+
+It's a good idea to search the tests for something related to the thing
+you're changing and you may find a test you can modify or adapt.
+
+To run the tests::
+
+ $ ./bzr selftest
+
+Normally the tests will skip if some library dependencies are not present.
+On Ubuntu, you can install them with this command (you must have some
+repositories enabled in Software Sources)::
+
+ $ sudo apt-get build-dep bzr
+
+To build the binary extensions::
+
+ $ make
+
+For more information: `Testing Guide <testing.html>`_.
+
+
+Proposing a merge
+-----------------
+
+
+Then propose a merge into bzr; for bzr 2.2 and later you can use the ``bzr
+propose-merge`` command. In the comment for your merge proposal please
+explain what you're trying to do and why. For `example
+<https://code.launchpad.net/~ian-clatworthy/bzr/whats-new-in-2.1/+merge/19677>`_:
+
+ As discussed on the mailing list, this patch adds a What's New document
+ summarising the changes since 2.0.
+
+If you make additional changes to your branch you don't need to resubmit;
+they'll automatically show up in the merge proposal.
+
+* `Launchpad Code Review Help <http://help.launchpad.net/Code/Review>`_.
+
..
vim: ft=rst tw=74 ai
More information about the bazaar-commits
mailing list