Merge lp:~mbp/bzr/doc into lp:bzr

[Martin Pool]

[Martin Pool (mbp)]

This tries to replace and update http://wiki.bazaar.canonical.com/BzrGivingBack and http://doc.bazaar.canonical.com/developers/contribution-quickstart.html with some clearer information and a somewhat more friendly (I feel) tone.

[Parth Malwankar (parthm)]

Looks useful to me.

review: Approve

[John A Meinel (jameinel)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Martin Pool wrote:
> Martin Pool has proposed merging lp:~mbp/bzr/doc into lp:bzr.
>
> Requested reviews:
> bzr-core (bzr-core)
> Related bugs:
> #473099 Incorrect markup in centralized workflow tutorial
> https://bugs.launchpad.net/bugs/473099
> #512385 Broken link to "quick start card" in online user guide
> https://bugs.launchpad.net/bugs/512385
>
>
> This tries to replace and update http://wiki.bazaar.canonical.com/BzrGivingBack and http://doc.bazaar.canonical.com/developers/contribution-quickstart.html with some clearer information and a somewhat more friendly (I feel) tone.
>

Looks good to me.

 merge: approve

Only bit would be:
+ [/home/mbp/bzr]
+ push_location = lp:~mbp/bzr/
+ push_location:policy = appendpath
+ public_branch = http://bazaar.launchpad.net/~mbp/bzr/
+ public_branch:policy = appendpath

You may want to s/mbp/USER/

Also, it may not be clear that it is

[/home/LOCAL_USER/bzr]
and
push_location = lp:~LP_USER/bzr/

or something like that.

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkt+3lUACgkQJdeBCYSNAANtgwCcCa++GsiiIfmgS4unbte+wV8Z
zi4An15X0JddQLwLbbgSoRMwFs/mQUvw
=jVFX
-----END PGP SIGNATURE-----

review: Approve

[lp:~mbp/bzr/doc]

5052. By Canonical.com Patch Queue Manager <email address hidden> on 2010-02-21

(robertc) Make bzrlib.commands.run_bzr more extensible and friendly
 to commandant and other external users. (Robert Collins)

5053. By Canonical.com Patch Queue Manager <email address hidden> on 2010-02-22

(Benjamin Beterson) Remove a pointlessly lazy import

5054. By Canonical.com Patch Queue Manager <email address hidden> on 2010-02-23

(mbp) better tips for contribution

=== modified file 'doc/developers/contribution-quickstart.txt'
--- doc/developers/contribution-quickstart.txt	2010-02-19 04:00:31 +0000
+++ doc/developers/contribution-quickstart.txt	2010-02-23 02:35:25 +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