Bazaar

Merge lp://staging/~nmb/bzr/hacking-giveback into lp://staging/~bzr/bzr/trunk-old

  1. hacking-giveback
  2. Merge into trunk-old
Proposed by Neil Martinsen-Burrell
Status: Merged
Approved by: John A Meinel
Approved revision: no longer in the source branch.
Merged at revision: not available
Proposed branch: lp://staging/~nmb/bzr/hacking-giveback
Merge into: lp://staging/~bzr/bzr/trunk-old
Diff against target: 211 lines
To merge this branch: bzr merge lp://staging/~nmb/bzr/hacking-giveback
Reviewer Review Type Date Requested Status
Martin Pool Approve
Review via email: mp+9893@code.staging.launchpad.net
To post a comment you must log in.
Revision history for this message
Neil Martinsen-Burrell (nmb) wrote :

This adds the brief introduction to contributing to Bazaar from the wiki at bazaar-vcs.org/BzrGivingBack as well as clearing up some drive-by typos in HACKING.txt. Hopefully this gives an accessible introduction to contributing that is supplemented by the existing material in HACKING.txt.

Revision history for this message
Martin Pool (mbp) wrote :

Thanks very much for merging it.

Just one point before a proper review: rather than suggesting people call their branch just 'giveback', suggest they call eg '403523-status-crash' to connect it to the bug they're working on, or something like 'doc' if it's a generic long-lived branch on a particular topic. One topic per branch.

Revision history for this message
Martin Pool (mbp) wrote :

That looks good to me.

On the whole I'm inclined to split HACKING into smaller task-specific pages:

 * it's a bit large to deal with in either a text editor or a web page
 * it's nice to be able to point people to just one document, rather than one section of a document, to show them how to get started.

But you don't need to do this now.

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'doc/en/developer-guide/HACKING.txt'
2--- doc/en/developer-guide/HACKING.txt 2009-07-31 14:52:10 +0000
3+++ doc/en/developer-guide/HACKING.txt 2009-08-13 18:36:21 +0000
4@@ -82,10 +82,77 @@
5 Bazaar Development in a Nutshell
6 ================================
7
8-Looking for a 10 minute introduction to submitting a change?
9-See http://bazaar-vcs.org/BzrGivingBack.
10-
11-TODO: Merge that Wiki page into this document.
12+.. was from bazaar-vcs.org/BzrGivingBack
13+
14+One of the fun things about working on a version control system like Bazaar is
15+that the users have a high level of proficiency in contributing back into
16+the tool. Consider the following very brief introduction to contributing back
17+to Bazaar. More detailed instructions are in the following sections.
18+
19+Making the change
20+-----------------
21+
22+First, get a local copy of the development mainline (See `Why make a local
23+copy of bzr.dev?`_.)
24+::
25+
26+ $ bzr init-repo ~/bzr
27+ $ cd ~/bzr
28+ $ bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
29+
30+Now make your own branch::
31+
32+ $ bzr branch bzr.dev giveback
33+
34+This will give you a branch called "giveback" that you can work on and commit
35+in. Here, you can study the code, make a fix or a new feature. Feel free to
36+commit early and often (after all, it's your branch!).
37+
38+Documentation improvements are an easy place to get started giving back to the
39+Bazaar project. The documentation is in the `doc/` subdirectory of the Bazaar
40+source tree.
41+
42+When you are done, make sure that you commit your last set of changes as well!
43+Once you are happy with your changes, ask for them to be merged, as described
44+below.
45+
46+Making a Merge Proposal
47+-----------------------
48+
49+The Bazaar developers use Launchpad to further enable a truly distributed
50+style of development. Anyone can propose a branch for merging into the Bazaar
51+trunk. To start this process, you need to push your branch to Launchpad. To
52+do this, you will need a Launchpad account and user name, e.g.
53+`your_lp_username`. You can push your branch to Launchpad directly from
54+Bazaar::
55+
56+ $ bzr push lp:~your_lp_username/bzr/giveback
57+
58+After you have pushed your branch, you will need to propose it for merging to
59+the Bazaar trunk. Go to <https://launchpad.net/your_lp_username/bzr/giveback>
60+and choose "Propose for merging into another branch". Select "~bzr/bzr/trunk"
61+to hand your changes off to the Bazaar developers for review and merging.
62+
63+Why make a local copy of bzr.dev?
64+---------------------------------
65+
66+Making a local mirror of bzr.dev is not strictly necessary, but it means
67+
68+- You can use that copy of bzr.dev as your main bzr executable, and keep it
69+ up-to-date using ``bzr pull``.
70+- Certain operations are faster, and can be done when offline. For example:
71+
72+ - ``bzr bundle``
73+ - ``bzr diff -r ancestor:...``
74+ - ``bzr merge``
75+
76+- When it's time to create your next branch, it's more convenient. When you
77+ have further contributions to make, you should do them in their own branch::
78+
79+ $ cd ~/bzr
80+ $ bzr branch bzr.dev additional_fixes
81+ $ cd additional_fixes # hack, hack, hack
82+
83
84
85 Understanding the Development Process
86@@ -135,7 +202,7 @@
87
88 bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev
89
90-* keep your copy of bzr.dev prestine (by not developing in it) and keep
91+* keep your copy of bzr.dev pristine (by not developing in it) and keep
92 it up to date (by using bzr pull)
93
94 * create a new branch off your local bzr.dev copy for each issue
95@@ -143,7 +210,7 @@
96
97 This approach makes it easy to go back and make any required changes
98 after a code review. Resubmitting the change is then simple with no
99-risk of accidentially including edits related to other issues you may
100+risk of accidentally including edits related to other issues you may
101 be working on. After the changes for an issue are accepted and merged,
102 the associated branch can be deleted or archived as you wish.
103
104@@ -191,7 +258,7 @@
105 is in the ReStructuredText markup language.
106
107 doc/developers
108- Documentation specifically targetted at Bazaar and plugin developers.
109+ Documentation specifically targeted at Bazaar and plugin developers.
110 (Including this document.)
111
112
113@@ -213,7 +280,7 @@
114 Good reviews do take time. They also regularly require a solid
115 understanding of the overall code base. In practice, this means a small
116 number of people often have a large review burden - with knowledge comes
117-responsibility. No one like their merge requests sitting in a queue going
118+responsibility. No one likes their merge requests sitting in a queue going
119 nowhere, so reviewing sooner rather than later is strongly encouraged.
120
121
122@@ -322,7 +389,7 @@
123
124 * <https://help.launchpad.net/Code/Review>
125
126-Anyone can propose or comment on a merge propsal just by creating a
127+Anyone can propose or comment on a merge proposal just by creating a
128 Launchpad account.
129
130 There are two ways to create a new merge proposal: through the web
131@@ -332,22 +399,24 @@
132 Proposing a merge through the web
133 ---------------------------------
134
135-To create the propsal through the web: push your branch to Launchpad, eg::
136+To create the proposal through the web, first push your branch to Launchpad.
137+For example, a branch dealing with documentation belonging to the Launchpad
138+User mbp could be pushed as ::
139
140 bzr push lp:~mbp/bzr/doc
141
142-then go to the branch's web page, which in this case would be
143-<https://code.launchpad.net/~mbp/bzr/doc>. You can automate that by just
144+Then go to the branch's web page, which in this case would be
145+<https://code.launchpad.net/~mbp/bzr/doc>. You can simplify this step by just
146 running ::
147
148 bzr lp-open
149
150-You can then click "Propose for merging into another branch", and enter a
151-cover letter into the web form. Typically you'll want to merge into
152-``~bzr/bzr/trunk`` which will be the default; you might also want to
153-nominate merging into a release branch for a bug fix. There is the option
154-to specify a specific reviewer or type of review, and you shouldn't
155-normally change those.
156+You can then click "Propose for merging into another branch", and enter your
157+cover letter (see above) into the web form. Typically you'll want to merge
158+into ``~bzr/bzr/trunk`` which will be the default; you might also want to
159+nominate merging into a release branch for a bug fix. There is the option to
160+specify a specific reviewer or type of review, and you shouldn't normally
161+change those.
162
163 Submitting the form takes you to the new page about the merge proposal
164 containing the diff of the changes, comments by interested people, and
165@@ -511,7 +580,7 @@
166 marmalade,
167 )
168
169-There should be spaces between function paramaters, but not between the
170+There should be spaces between function parameters, but not between the
171 keyword name and the value::
172
173 call(1, 3, cheese=quark)
174@@ -799,7 +868,7 @@
175 _function or ...) behind which forwards to the new API. See the
176 bzrlib.symbol_versioning module for decorators that take care of the
177 details for you - such as updating the docstring, and issuing a warning
178-when the old api is used.
179+when the old API is used.
180
181 For unsupported API's, it does not hurt to follow this discipline, but it's
182 not required. Minimally though, please try to rename things so that
183@@ -922,7 +991,7 @@
184 The user should call `finish` on the `ProgressTask` when the logical
185 operation has finished, so it can be removed from the stack.
186
187-Progress tasks have a complex relatioship with generators: it's a very
188+Progress tasks have a complex relationship with generators: it's a very
189 good place to use them, but because python2.4 does not allow ``finally``
190 blocks in generators it's hard to clean them up properly. In this case
191 it's probably better to have the code calling the generator allocate a
192@@ -1236,8 +1305,8 @@
193 Attempting to print an unprintable character will cause a UnicodeError.
194 This is for commands that are intended more as scripting support, rather
195 than plain user review.
196- For exampl: ``bzr ls`` is designed to be used with shell scripting. One
197- use would be ``bzr ls --null --unknows | xargs -0 rm``. If ``bzr``
198+ For example: ``bzr ls`` is designed to be used with shell scripting. One
199+ use would be ``bzr ls --null --unknowns | xargs -0 rm``. If ``bzr``
200 printed a filename with a '?', the wrong file could be deleted. (At the
201 very least, the correct file would not be deleted). An error is used to
202 indicate that the requested action could not be performed.
203@@ -1542,7 +1611,7 @@
204 https://blueprints.launchpad.net/bzr/. Once a blueprint for ready for
205 review, please announce it on the mailing list.
206
207-Alternatively, send an email begining with [RFC] with the proposal to the
208+Alternatively, send an email beginning with [RFC] with the proposal to the
209 list. In some cases, you may wish to attach proposed code or a proposed
210 developer document if that best communicates the idea. Debate can then
211 proceed using the normal merge review processes.