~bzr-pqm/bzr/bzr.dev : revision 4604

82

Bazaar Development in a Nutshell

83

================================

84

85

Looking for a 10 minute introduction to submitting a change?

86

See http://bazaar-vcs.org/BzrGivingBack.

87

88

TODO: Merge that Wiki page into this document.

85

.. was from bazaar-vcs.org/BzrGivingBack

86

87

One of the fun things about working on a version control system like Bazaar is

88

that the users have a high level of proficiency in contributing back into

89

the tool. Consider the following very brief introduction to contributing back

90

to Bazaar. More detailed instructions are in the following sections.

91

92

Making the change

93

-----------------

94

95

First, get a local copy of the development mainline (See `Why make a local

96

copy of bzr.dev?`_.)

97

::

98

99

$ bzr init-repo ~/bzr

100

$ cd ~/bzr

101

$ bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev

102

103

Now make your own branch::

104

105

$ bzr branch bzr.dev 123456-my-bugfix

106

107

This will give you a branch called "123456-my-bugfix" that you can work on

108

and commit in. Here, you can study the code, make a fix or a new feature.

109

Feel free to commit early and often (after all, it's your branch!).

110

111

Documentation improvements are an easy place to get started giving back to the

112

Bazaar project. The documentation is in the `doc/` subdirectory of the Bazaar

113

source tree.

114

115

When you are done, make sure that you commit your last set of changes as well!

116

Once you are happy with your changes, ask for them to be merged, as described

117

below.

118

119

Making a Merge Proposal

120

-----------------------

121

122

The Bazaar developers use Launchpad to further enable a truly distributed

123

style of development. Anyone can propose a branch for merging into the Bazaar

124

trunk. To start this process, you need to push your branch to Launchpad. To

125

do this, you will need a Launchpad account and user name, e.g.

126

`your_lp_username`. You can push your branch to Launchpad directly from

127

Bazaar::

128

129

$ bzr push lp:~your_lp_username/bzr/giveback

130

131

After you have pushed your branch, you will need to propose it for merging to

132

the Bazaar trunk. Go to <https://launchpad.net/your_lp_username/bzr/giveback>

133

and choose "Propose for merging into another branch". Select "~bzr/bzr/trunk"

134

to hand your changes off to the Bazaar developers for review and merging.

135

136

Why make a local copy of bzr.dev?

137

---------------------------------

138

139

Making a local mirror of bzr.dev is not strictly necessary, but it means

140

141

- You can use that copy of bzr.dev as your main bzr executable, and keep it

142

up-to-date using ``bzr pull``.

143

- Certain operations are faster, and can be done when offline. For example:

144

145

- ``bzr bundle``

146

- ``bzr diff -r ancestor:...``

147

- ``bzr merge``

148

149

- When it's time to create your next branch, it's more convenient. When you

150

have further contributions to make, you should do them in their own branch::

151

152

$ cd ~/bzr

153

$ bzr branch bzr.dev additional_fixes

154

$ cd additional_fixes # hack, hack, hack

155

89

156

90

157

91

158

Understanding the Development Process

135

202

136

203

bzr branch http://bazaar-vcs.org/bzr/bzr.dev/ bzr.dev

137

204

138

* keep your copy of bzr.dev prestine (by not developing in it) and keep

205

* keep your copy of bzr.dev pristine (by not developing in it) and keep

139

206

it up to date (by using bzr pull)

140

207

141

208

* create a new branch off your local bzr.dev copy for each issue

143

210

144

211

This approach makes it easy to go back and make any required changes

145

212

after a code review. Resubmitting the change is then simple with no

146

risk of accidentially including edits related to other issues you may

213

risk of accidentally including edits related to other issues you may

147

214

be working on. After the changes for an issue are accepted and merged,

148

215

the associated branch can be deleted or archived as you wish.

149

216

191

258

is in the ReStructuredText markup language.

192

259

193

260

doc/developers

194

Documentation specifically targetted at Bazaar and plugin developers.

261

Documentation specifically targeted at Bazaar and plugin developers.

195

262

(Including this document.)

196

263

197

264

213

280

Good reviews do take time. They also regularly require a solid

214

281

understanding of the overall code base. In practice, this means a small

215

282

number of people often have a large review burden - with knowledge comes

216

responsibility. No one like their merge requests sitting in a queue going

283

responsibility. No one likes their merge requests sitting in a queue going

217

284

nowhere, so reviewing sooner rather than later is strongly encouraged.

218

285

219

286

322

389

323

390

* <https://help.launchpad.net/Code/Review>

324

391

325

Anyone can propose or comment on a merge propsal just by creating a

392

Anyone can propose or comment on a merge proposal just by creating a

326

393

Launchpad account.

327

394

328

395

There are two ways to create a new merge proposal: through the web

332

399

Proposing a merge through the web

333

400

---------------------------------

334

401

335

To create the propsal through the web: push your branch to Launchpad, eg::

402

To create the proposal through the web, first push your branch to Launchpad.

403

For example, a branch dealing with documentation belonging to the Launchpad

404

User mbp could be pushed as ::

336

405

337

406

bzr push lp:~mbp/bzr/doc

338

407

339

then go to the branch's web page, which in this case would be

340

<https://code.launchpad.net/~mbp/bzr/doc>. You can automate that by just

408

Then go to the branch's web page, which in this case would be

409

<https://code.launchpad.net/~mbp/bzr/doc>. You can simplify this step by just

341

410

running ::

342

411

343

412

bzr lp-open

344

413

345

You can then click "Propose for merging into another branch", and enter a

346

cover letter into the web form. Typically you'll want to merge into

347

``~bzr/bzr/trunk`` which will be the default; you might also want to

348

nominate merging into a release branch for a bug fix. There is the option

349

to specify a specific reviewer or type of review, and you shouldn't

350

normally change those.

414

You can then click "Propose for merging into another branch", and enter your

415

cover letter (see above) into the web form. Typically you'll want to merge

416

into ``~bzr/bzr/trunk`` which will be the default; you might also want to

417

nominate merging into a release branch for a bug fix. There is the option to

418

specify a specific reviewer or type of review, and you shouldn't normally

419

change those.

351

420

352

421

Submitting the form takes you to the new page about the merge proposal

353

422

containing the diff of the changes, comments by interested people, and

511

580

marmalade,

512

581

)

513

582

514

There should be spaces between function paramaters, but not between the

583

There should be spaces between function parameters, but not between the

515

584

keyword name and the value::

516

585

517

586

call(1, 3, cheese=quark)

799

868

_function or ...) behind which forwards to the new API. See the

800

869

bzrlib.symbol_versioning module for decorators that take care of the

801

870

details for you - such as updating the docstring, and issuing a warning

802

when the old api is used.

871

when the old API is used.

803

872

804

873

For unsupported API's, it does not hurt to follow this discipline, but it's

805

874

not required. Minimally though, please try to rename things so that

922

991

The user should call `finish` on the `ProgressTask` when the logical

923

992

operation has finished, so it can be removed from the stack.

924

993

925

Progress tasks have a complex relatioship with generators: it's a very

994

Progress tasks have a complex relationship with generators: it's a very

926

995

good place to use them, but because python2.4 does not allow ``finally``

927

996

blocks in generators it's hard to clean them up properly. In this case

928

997

it's probably better to have the code calling the generator allocate a

1236

1305

Attempting to print an unprintable character will cause a UnicodeError.

1237

1306

This is for commands that are intended more as scripting support, rather

1238

1307

than plain user review.

1239

For exampl: ``bzr ls`` is designed to be used with shell scripting. One

1240

use would be ``bzr ls --null --unknows | xargs -0 rm``. If ``bzr``

1308

For example: ``bzr ls`` is designed to be used with shell scripting. One

1309

use would be ``bzr ls --null --unknowns | xargs -0 rm``. If ``bzr``

1241

1310

printed a filename with a '?', the wrong file could be deleted. (At the

1242

1311

very least, the correct file would not be deleted). An error is used to

1243

1312

indicate that the requested action could not be performed.

1542

1611

https://blueprints.launchpad.net/bzr/. Once a blueprint for ready for

1543

1612

review, please announce it on the mailing list.

1544

1613

1545

Alternatively, send an email begining with [RFC] with the proposal to the

1614

Alternatively, send an email beginning with [RFC] with the proposal to the

1546

1615

list. In some cases, you may wish to attach proposed code or a proposed

1547

1616

developer document if that best communicates the idea. Debate can then

1548

1617

proceed using the normal merge review processes.