← Back to branch summary

~bzr/ubuntu/lucid/bzr/beta-ppa

« back to all changes in this revision

Viewing changes to doc/en/tutorials/using_bazaar_with_launchpad.txt

  • Committer: Martin Pool
  • Date: 2010-07-02 07:29:40 UTC
  • mfrom: (129.1.7 packaging-karmic)
  • Revision ID: mbp@sourcefrog.net-20100702072940-hpzq5elg8wjve8rh
http://bugs.debian.org/452024
http://bugs.debian.org/464688
http://bugs.debian.org/523595
http://bugs.debian.org/526233
http://bugs.debian.org/537708
http://bugs.debian.org/555336
http://bugs.debian.org/555343
https://launchpad.net/bugs/249452
https://launchpad.net/bugs/385074
* PPA rebuild.
* PPA rebuild for Karmic.
* PPA rebuild for Jaunty.
* PPA rebuild for Hardy.
* From postinst, actually remove the example bash completion scripts.
  (LP: #249452)
* New upstream release.
* New upstream release.
* New upstream release.
* Revert change to Build-depends: Dapper does not have python-central.
  Should be python-support..
* Target ppa..
* Target ppa..
* Target ppa..
* Target ppa..
* New upstream release.
* Switch to dpkg-source 3.0 (quilt) format.
* Bump standards version to 3.8.4.
* Remove embedded copy of python-configobj. Closes: #555336
* Remove embedded copy of python-elementtree. Closes: #555343
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* debian/control: Fix obsolete-relation-form-in-source
  lintian warning. 
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Split out docs into bzr-doc package.
* New upstream release.
* Added John Francesco Ferlito to Uploaders.
* Fix install path to quick-reference guide
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again, again.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to path changes.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Bump standards version to 3.8.3.
* Remove unused patch system.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix copy and paste tab error in .install file
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
 + Fixes compatibility with Python 2.4. Closes: #537708
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream version.
* Bump standards version to 3.8.2.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add python-pyrex to build-deps to ensure C extensions are always build.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix API compatibility version. (Closes: #526233)
* New upstream release.
  + Fixes default format for upgrade command. (Closes: #464688)
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add missing dependency on zlib development library. (Closes:
  #523595)
* Add zlib build-depends.
* Add zlib build-depends.
* Add zlib build-depends.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Move to section vcs.
* Bump standards version to 3.8.1.
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Recommend ca-certificates. (Closes: #452024)
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Update watch file. bazaar now uses launchpad to host its sources.
* Remove patch for inventory root revision copy, applied upstream.
* New upstream release.
* New upstream release.
* New upstream release
* Force removal of files installed in error to /etc/bash_completion.d/
  (LP: #249452)
* New upstream release.
* New upstream release
* New upstream release.
* Bump standards version.
* Include patch for inventory root revision copy, required for bzr-svn.
* New upstream release.
* Remove unused lintian overrides.
* Correct the package version not to be native.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Final 1.5 release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add myself as a co-maintainer.
* Add a Dm-Upload-Allowed: yes header.
* New upstream bugfix release.
* New upstream release.
* Final 1.3 release.
* New upstream release.
* First release candidate of the upcoming 1.3 release.
* Rebuild to fix the problem caused by a build with a broken python-central.
* New upstream release.
* Rebuild for dapper PPA.
* Apply Lamont's patches to fix build-dependencies on dapper.
  (See: https://bugs.launchpad.net/bzr/+bug/189915)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/tutorials/using_bazaar_with_launchpad.txt
 
1
===========================
 
2
Using Bazaar with Launchpad
 
3
===========================
 
4
 
 
5
 
 
6
Motivation
 
7
==========
 
8
 
 
9
Communities are different to teams
 
10
----------------------------------
 
11
 
 
12
The team of people required to create the initial release
 
13
of a piece of software may vary in size from one person
 
14
to several thousand people. Depending on the requirements,
 
15
the challenges involved, both technical and managerial,
 
16
can be immense. As explained in the Bazaar User Guide, selecting
 
17
"just right" processes and using tools like Bazaar to support
 
18
matching workflows can greatly help.
 
19
 
 
20
Success with software though requires more than a great team - it
 
21
requires a healthy, active *community*. This group is typically
 
22
far larger than the team as it includes everyone interested in
 
23
the software: the team, users, training partners, support partners,
 
24
third-party developers and so on.
 
25
 
 
26
Great communities are well understood in the open source world.
 
27
Their applicability extends well beyond that though: most
 
28
successful commercial software vendors are well skilled at
 
29
building and managing the communities that grow up around
 
30
their flagship products.
 
31
 
 
32
Like great teams, great communities don't just happen.
 
33
Good policies and guidelines are essential for
 
34
fostering the right sort of behaviour and healthy
 
35
relationships between participants. For a deeper look at
 
36
this topic, see Karl Fogel's landmark book:
 
37
`Producing Open Source Software <http://www.producingoss.com/>`_.
 
38
 
 
39
 
 
40
The need for Collaborative Development Environments
 
41
---------------------------------------------------
 
42
 
 
43
An intelligent toolset is also important for tracking and managing
 
44
community information and workflows. These tools are called
 
45
Collaborative Development Environments (CDEs). These toolsets are
 
46
typically web-based and manage things such as announcements,
 
47
issues/bugs, questions and answers, downloads, documents and
 
48
source code. Some examples of CDEs include
 
49
`Launchpad <https://launchpad.net>`_,
 
50
`SourceForge <http://sourceforge.net>`_,
 
51
`java.net <http://java.net>`_ and
 
52
`SAP Community Network <https://www.sdn.sap.com/irj/sdn>`_.
 
53
 
 
54
 
 
55
Helping communities work with related communities
 
56
-------------------------------------------------
 
57
 
 
58
Many successful products have a huge number of downstream dependencies.
 
59
In other words, a new challenge arises with success: dealing with other
 
60
communities and understanding how your changes will impact them. This is
 
61
most obvious for projects like:
 
62
 
 
63
* software languages, e.g. Python, PHP, Ruby, Java, Perl, etc.
 
64
* compilers, e.g. gcc, JDK, etc.
 
65
* libraries, e.g. zlib, openssl, etc.
 
66
* frameworks, e.g. Zope, Ruby on Rails, Spring, etc.
 
67
 
 
68
However it applies equally for popular applications on which add-ons are
 
69
built, e.g. Firefox, Thunderbird, OpenOffice.org, Drupal, Wordpress, Joomla,
 
70
etc.
 
71
 
 
72
Tools that assist communities work together to track and manage
 
73
issues and fixes across community boundaries are required. These
 
74
tools help people at both ends of the spectrum:
 
75
 
 
76
* users can report problems in their terms, e.g. rendering of image
 
77
  type X is broken in application Y on operating system Z
 
78
 
 
79
* developers can better appreciate the downstream impact of making a
 
80
  change or fix, e.g. fixing this bug in a graphics library will
 
81
  make the users of these 5 applications on these 10 operating
 
82
  systems happy.
 
83
 
 
84
People in the middle play the essential role of *joining the dots* and
 
85
communicating up and down the line. In many cases, they may also fix the
 
86
problem for end users, releasing a patch and pushing a suggested fix
 
87
to the upstream development team. Keeping track of all that over time
 
88
in a sustainable way is no easy task.
 
89
 
 
90
 
 
91
Launchpad: More development, less friction
 
92
------------------------------------------
 
93
 
 
94
As well as sponsoring `Ubuntu <http://www.ubuntu.com>`_ and
 
95
`Bazaar <http://bazaar-vcs.org>`_ development, Canonical
 
96
provides Launchpad, https://launchpad.net, as a free service
 
97
for the open source community. Launchpad is one of the most
 
98
exciting CDEs around for several notable reasons:
 
99
 
 
100
* it models relationships between many of things tracked, e.g.
 
101
  source code branches can be associated with bug fixes
 
102
 
 
103
* as well are managing historical knowledge,
 
104
  it supports future development planning and tracking by providing
 
105
  features such as roadmaps, milestones and blueprints
 
106
 
 
107
* it provides translation tools and packaging services so that
 
108
  barriers are reduced for translators and testers wishing to
 
109
  join your community and help out
 
110
 
 
111
* it provides a nexus for different communities to work
 
112
  together on related issues and roadmaps.
 
113
 
 
114
In other words, Launchpad has been designed to help your
 
115
community grow and to reduce the workflow friction both
 
116
*within* your community and *between* communities. Ultimately,
 
117
that means less time on mechanical tasks and more time for
 
118
interesting development.
 
119
 
 
120
 
 
121
Bazaar: Launchpad's VCS client
 
122
------------------------------
 
123
 
 
124
This tutorial looks at how Bazaar and Launchpad can be used together
 
125
and how they complement each other. It is important to remember that:
 
126
 
 
127
1. Bazaar can be used without Launchpad
 
128
2. Launchpad can be used without Bazaar.
 
129
 
 
130
By design though, their sum is greater than the individual
 
131
parts.
 
132
 
 
133
 
 
134
Finding and browsing branches using Launchpad
 
135
=============================================
 
136
 
 
137
Finding available branches
 
138
--------------------------
 
139
 
 
140
While there are many advantages in adopting distributed version
 
141
control, one of the things that disappears is the all-knowing
 
142
central server with knowledge about all available branches. Indeed
 
143
in a distributed environment, interesting branches can literally
 
144
exist in 100s of locations across the Internet (or within an
 
145
Intranet for that matter).
 
146
 
 
147
Launchpad fills this gap by providing a registry of branches.
 
148
 
 
149
 
 
150
Registering branches
 
151
--------------------
 
152
 
 
153
Branches can be uploaded to Launchpad or simply registered
 
154
as being available in an external location. Branches can also
 
155
be given a Status such as *New*, *Development*, *Mature* or
 
156
*Abandoned*.
 
157
 
 
158
Note: External branches can even be hosted in legacy version control
 
159
tools, i.e. CVS and Subversion. Code in these systems will be
 
160
scanned and converted to Bazaar branches on a periodic basis.
 
161
For maximum fidelity of course, it is preferable for external
 
162
branches to be hosted in Bazaar.
 
163
 
 
164
 
 
165
Browsing branches
 
166
-----------------
 
167
 
 
168
Branches can be listed, filtered and sorted by numerous
 
169
attributes including Name, Registrant, Author, Status, Age and
 
170
time of last commit. Browsing of branches is also provided making
 
171
it easy to see things such as:
 
172
 
 
173
* where the branch can be downloaded from
 
174
* how to upload changes
 
175
* recent commits and the changes made by each
 
176
* the source code of individual files for a given version.
 
177
 
 
178
 
 
179
Accessing code in Launchpad using Bazaar
 
180
========================================
 
181
 
 
182
Getting the code for an open source project
 
183
-------------------------------------------
 
184
 
 
185
As Launchpad keeps track of thousands of open source projects
 
186
and their latest code whether it be managed by Bazaar, CVS or Subversion,
 
187
Bazaar users can grab that code as easily as this::
 
188
 
 
189
  bzr branch lp:project-name
 
190
 
 
191
where `project-name` is the Launchpad project ID. Here are some examples::
 
192
 
 
193
  bzr branch lp:inkscape
 
194
  bzr branch lp:amarok
 
195
  bzr branch lp:python
 
196
  bzr branch lp:rails
 
197
  bzr branch lp:java-gnome
 
198
 
 
199
You can then browse the code locally using your favorite editor or IDE and
 
200
change the code if you wish.
 
201
 
 
202
If a project has multiple series registered (e.g. a development series and a
 
203
maintenance series), the latest code for a given series can be fetched using::
 
204
 
 
205
  bzr branch lp:project-name/series
 
206
 
 
207
Publishing your changes
 
208
-----------------------
 
209
 
 
210
Having fixed that annoying bug or added that cool feature you've always
 
211
wanted, it's time to impress your friends and make the world a better
 
212
place by making your code available to others. As explained earlier,
 
213
Launchpad is a free Bazaar code hosting service so you can push your
 
214
branch to it and others can access your code from there. For example,
 
215
assuming you are a member of the relevant team, login to launchpad like this::
 
216
 
 
217
  bzr launchpad-login userid
 
218
 
 
219
where `userid` is your Launchpad user ID.
 
220
You can then push your changes to a team branch like this::
 
221
 
 
222
  bzr push lp:~team-name/project-name/branch-name
 
223
 
 
224
Others can then download your code like this::
 
225
 
 
226
  bzr branch lp:~team-name/project-name/branch-name
 
227
 
 
228
 
 
229
Personal branches
 
230
-----------------
 
231
 
 
232
Even if you are not a member of a team, Launchpad can be used to publish
 
233
your changes. In this case, simply create a personal branch like this::
 
234
 
 
235
  bzr push lp:~userid/project-name/branch-name
 
236
 
 
237
Others can then download your code like this::
 
238
 
 
239
  bzr branch lp:~userid/project-name/branch-name
 
240
 
 
241
Note: Even when publishing to a personal branch, it is polite to notify the
 
242
upstream developers about your branch so they can pull your changes from
 
243
it if they are generally applicable to all users and meet the project's
 
244
quality standards.
 
245
 
 
246
 
 
247
Linking branches using Launchpad
 
248
================================
 
249
 
 
250
Associating a branch with a bug
 
251
-------------------------------
 
252
 
 
253
After registering a branch, you can associate it to a bug so that
 
254
people interested in that bug can track and download the fix as
 
255
it becomes available.
 
256
 
 
257
To do this, the steps are:
 
258
 
 
259
1. Navigate to the bug in question.
 
260
 
 
261
2. Select `Add branch` under `Actions`.
 
262
 
 
263
3. Select the branch.
 
264
 
 
265
4. Optionally set the State of the relationship. This is
 
266
   *Fix In Progress* by default but you may wish to set it
 
267
   to another state such as *Fix Available* if the branch already
 
268
   addresses the issue.
 
269
 
 
270
If you wish, you can also provide some arbitrary comments about
 
271
the relationship between the bug and the branch.
 
272
 
 
273
 
 
274
Changing the state in Launchpad while committing in Bazaar
 
275
----------------------------------------------------------
 
276
 
 
277
Bazaar and Launchpad can work together to reduce some of
 
278
the status housekeeping for you. When you commit using Bazaar,
 
279
use the --fixes option like this::
 
280
 
 
281
  bzr commit --fixes lp:1234 -m "..."
 
282
 
 
283
where 1234 is the bug ID. This will changes the State of the
 
284
bug-branch relationship to *Fix Available*. If the one commit
 
285
fixes multiple issues, the --fixes option can be specified multiple
 
286
times.
 
287
 
 
288
One of the cool things about this feature is that Launchpad does
 
289
not need to be accessible when making the commit. The ``--fixes``
 
290
option works by storing metadata which Launchpad will detect next
 
291
time the branch is pushed to it or scanned once online again.
 
292
 
 
293
Note: Launchpad will not implicitly close a bug just because a
 
294
branch is available that fixes it. There are several reasons for this.
 
295
Firstly, the branch usually needs to be merged into the trunk
 
296
(main development branch) before most teams consider it fixed.
 
297
Secondly, many teams have a separate process for confirming
 
298
bugs are fixed over and above a developer saying so.
 
299
 
 
300
As explained later, merge control features are currently under
 
301
development in Launchpad and automatically changing the status of
 
302
bugs to *Fix Committed* will be more appropriate once those features
 
303
are in place.
 
304
 
 
305
 
 
306
Associating a branch with a blueprint
 
307
-------------------------------------
 
308
 
 
309
After registering a branch, you can associate it to a blueprint so that
 
310
people interested in that blueprint can track and test the feature as
 
311
it develops.
 
312
 
 
313
To do this, the steps are:
 
314
 
 
315
1. Navigate to the blueprint in question.
 
316
 
 
317
2. Select `Link branch` under `Actions`.
 
318
 
 
319
3. Select the branch.
 
320
 
 
321
If you wish, you can also provide some arbitrary comments about
 
322
the relationship between the blueprint and the branch.
 
323
 
 
324
 
 
325
Managing releases using Launchpad
 
326
=================================
 
327
 
 
328
Integrating changes
 
329
-------------------
 
330
 
 
331
Once a branch has been developed and published, communities
 
332
typically go through a rigorous process before those changes
 
333
are integrated into the core product and rolled out to end users.
 
334
Some of the steps involved may include:
 
335
 
 
336
* peer review of the changes
 
337
 
 
338
* deciding which releases to include the changes in, e.g. the
 
339
  next maintenance release, the next major release, or both
 
340
 
 
341
* running functional regression tests
 
342
 
 
343
* benchmarking to ensure performance remains acceptable
 
344
 
 
345
* packaging into early access releases for end user testing
 
346
 
 
347
* documentation updates, e.g. Release Notes for the targeted
 
348
  releases
 
349
 
 
350
* translation of the user interface and documentation into
 
351
  multiple languages.
 
352
 
 
353
This section briefly looks at some of the features in Launchpad that
 
354
help get good quality code into production. Strong integration with
 
355
Bazaar is core to making this happen smoothly.
 
356
 
 
357
Note: Where indicated, some of the features below are still under
 
358
development. If one or more of these features interest you, please
 
359
consider joining the Launchpad beta test team at this link:
 
360
https://help.launchpad.net/JoiningLaunchpadBetaTesters. You can
 
361
then get early access to features and provide feedback to the
 
362
developers before wider roll-out.
 
363
 
 
364
 
 
365
Branch merge proposals
 
366
----------------------
 
367
 
 
368
After navigating to a branch in Launchpad, one of the available actions
 
369
is *Propose for merging*. This lets you nominate which branch this code
 
370
ought to be merged into.
 
371
 
 
372
Tracking the knowledge about which branches are proposed to be merged
 
373
into a codeline helps Release Managers keep on top of what still needs
 
374
to be completed, or can be completed, before a ship date. Using this
 
375
information, they can ensure branches are merged after completing any
 
376
necessary reviews. In the simple case, the Release Manager may manually
 
377
merge branches. In more advanced cases, the merging could be automatically
 
378
done by a robot (like `PQM`_) when the branch reaches the right state
 
379
(e.g. *Review completed*).
 
380
 
 
381
.. _PQM: https://launchpad.net/pqm
 
382
 
 
383
 
 
384
Code review tracking
 
385
--------------------
 
386
 
 
387
A number of features are under development in Launchpad to track the
 
388
states, conversations and outcomes of code reviews. These features are
 
389
expected to be integrated with branch merge proposals and branch
 
390
browsing features.
 
391
 
 
392
 
 
393
Personal Package Archives (PPAs)
 
394
--------------------------------
 
395
 
 
396
PPAs help developers and development teams get custom builds into the
 
397
hands of users for early testing and feedback. In other words, a PPA
 
398
allows a developer to form a community of testers who are interested
 
399
in their changes. The testing community can install the packages,
 
400
run them for the test period and then remove them cleanly from their
 
401
system.
 
402
 
 
403
See https://help.launchpad.net/PPAQuickStart for further details.
 
404
 
 
405
 
 
406
Translations
 
407
------------
 
408
 
 
409
The Translations module in Launchpad is designed to make it easy for
 
410
anyone to get involved translating applications to languages they know.
 
411
Translators are shielded from the low level details.
 
412
 
 
413
Launchpad keeps track of the translations for each major version of a
 
414
project separately, allowing translators to continue to improve the
 
415
translations of your stable releases while others start work on newer
 
416
versions that are still in development. Translation speed in reduced
 
417
by sharing resources across projects. Automatic suggestions, from a
 
418
library of 750,000 translated strings, and a community of 19,000
 
419
registered translators can radically cut the time required to
 
420
localise your project into many languages.
 
421
 
 
422
 
 
423
Summary
 
424
=======
 
425
 
 
426
The communities we join, whether off-line or on-line,
 
427
say a lot about the sort of people we are. The flip-side
 
428
to this is that the tools you choose for your community - particularly
 
429
the CDE and version control tool - can have a large impact on who
 
430
joins and how easily they can contribute.
 
431
 
 
432
In their own right, Launchpad and Bazaar are highly useful tools.
 
433
Together, they can:
 
434
 
 
435
* help your community track major assets such as source code and knowledge
 
436
* help it grow by reducing barriers to entry
 
437
* help it interact with related communities.
 
438
 
 
439
In particular, Launchpad is a free code hosting service for your Bazaar
 
440
branches, branches can be browsed online, branches can be linked to bugs
 
441
and blueprints, and the status of bug-branch relationships can be
 
442
automatically managed by mentioning the bug while committing in Bazaar.
 
443
Further integration is under development with the aim of streamlining
 
444
the process from *great idea* to *running code in the hands of end users*.
 
445
 
 
446
If you have any feedback on how you'd like to see Bazaar and Launchpad
 
447
further integrated, please contact us on the Bazaar mailing list,
 
448
bazaar@lists.canonical.com.
 
449
 
 
450
While designed as a free service to support open source projects,
 
451
Canonical may make Launchpad available to commercial software developers
 
452
depending on their requirements. We would be happy to hear from you
 
453
if you think Launchpad would be useful for managing your community,
 
454
open source or otherwise.