← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/workflow.txt

  • Committer: Robert Collins
  • Date: 2010-04-08 04:34:03 UTC
  • mfrom: (5138 +trunk)
  • mto: This revision was merged to the branch mainline in revision 5139.
  • Revision ID: robertc@robertcollins.net-20100408043403-56z0d07vdqrx7f3t
Update bugfix for 528114 to trunk.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/workflow.txt
1
 
********
2
 
Workflow
3
 
********
4
 
 
5
 
People want to manage submissions of patches; see `Havoc's post`__.
6
 
 
7
 
__ http://log.ometer.com/2004-11.html#19
8
 
 
9
 
The ideal interface is::
10
 
 
11
 
    baz branch http://project.org/bzr/project-2.0
12
 
    [hackety hack]
13
 
    baz submit
14
 
 
15
 
It would be nice if people could submit simple changes without needing
16
 
to set up their own public branches.  I don't think people will want
17
 
to allow random strangers to create branches on their machine, so this
18
 
probably means submitting the changes by email.  To form such a patch
19
 
we need to know what branch point counts as "upstream", and who to
20
 
send the patches to.  As a reasonable default, we might use the last
21
 
time we branched and the last 
22
 
 
23
 
Some of this should be better done in integration with e.g. mail
24
 
clients or external robots or bug trackers. 
25
 
 
26
 
Bazaar-NG allows redrafting rejected patches in an interesting way: 
27
 
 
28
 
  Person writes a feature on a new feature branch.  They can commit
29
 
  several times, merge up to date, even have sub-forks to an arbitrary
30
 
  extent.  When they're ready, they submit their changes to the
31
 
  maintainer, either by mailing the diffs relative to the main branch,
32
 
  or by the maintainer pulling from their tree.   If they don't like
33
 
  it, they can not commit it to their tree, and hopefully give some
34
 
  feedback to the contributor.  (I don't think that feedback needs to
35
 
  go back through the tool; email or some other communication
36
 
  mechanism is probably fine.)  The contributor can then keep working
37
 
  in their branch, until it eventually gets merged.
38
 
 
39
 
  Alternatively, the maintainer might want to merge the change but fix
40
 
  it up themselves.  We keep track of the fact that it was merged, and
41
 
  the maintainer can make arbitrary fixups either in the course of
42
 
  merging it or afterwards.  When the contributor later merges back
43
 
  everything will work.
44
 
 
45
 
  Another case is that the maintainer wants to improve the patch but
46
 
  not take it into their main tree.  What they can do here is take it
47
 
  into a separate feature branch, fix it up, and then ask the
48
 
  contributor to merge back from there.
49
 
 
50
 
Maintainers__ would also like to keep track of patches that have been
51
 
submitted but not yet accepted, so they're not lost and can be
52
 
updated.  One way to do this would be to create a branch on the
53
 
maintainer's machine for a submitted patch, and apply the submission
54
 
to that.  The maintainer can fix it if they want, or take updates to
55
 
it.  The submitter can see what, if anything, was done.  Because this
56
 
branch is identified by a URL it can be cited in bug reports, and it
57
 
might make sense to name the branch by the bug it is supposed to fix.
58
 
 
59
 
__ http://gcc.gnu.org/ml/gcc/2002-12/msg00444.html
60
 
 
61
 
 
62
 
 
63
 
Aegis-style review and integration
64
 
----------------------------------
65
 
 
66
 
Some projects might want all changes to be submitted for review before
67
 
merging onto the mainline.  This might be done either by convention,
68
 
or perhaps by not allowing individual developers to merge to the
69
 
mainline but rather having specific privileged integrators.
70
 
 
71
 
Aegis_ enforces a lot of workflow/process; it would be good to be able
72
 
to do something similar on top of bazaar-ng either manually or as a
73
 
higher-level tool.  Aegis's model is that each proposed change is
74
 
essentially on a branch that later merges into the mainline, which
75
 
makes a lot of sense.
76
 
 
77
 
.. _Aegis: compared-aegis.html
78
 
 
79
 
To do something like Aegis, follow this process:
80
 
 
81
 
* Developer makes a new branch from the trunk to develop a feature,
82
 
  called say ``project--devel--bug-123``.
83
 
 
84
 
* When they have almost finished development, they re-merge from the
85
 
  trunk to make sure they're up to date.
86
 
 
87
 
* By some mechanism they ask a reviewer to consider their changes --
88
 
  perhaps by sending email, or using a bug tracking system, or
89
 
  something else.  They tell the reviewer the location of their
90
 
  branch, which might be on an HTTP server for a public project, or on
91
 
  a directory on a shared server.
92
 
 
93
 
* The reviewer makes a new branch for review based off the trunk,
94
 
  ``project--review--bug-123``, and merges the development branch into
95
 
  it.  The merge should be perfect if the developer was up to date
96
 
  with the trunk.  If the merge fails they can either bounce it back
97
 
  to the developer or fix the merge themselves according to local
98
 
  policy or their own discretion.  They then review, build and test
99
 
  the branch.  If it's OK, they commit to their review branch and send
100
 
  a note asking for it to be integrated (or perhaps they integrate
101
 
  themselves.)
102
 
 
103
 
* The integrator merges from the review branch onto the trunk,
104
 
  builds/tests and commits.  Since they pull from the reviewer's
105
 
  branch there is no way unreviewed changes can sneak through even if
106
 
  the developer adds to their work branch after the review.
107
 
  
108
 
  This can be done by a robot, or by a reviewer.
109
 
 
110
 
* The developer can look at the review, integration and trunk branches
111
 
  to see that their changes have merged.
112
 
 
113
 
This model is practiced by some people at Canonical using tla.  Since
114
 
people work within a complex configspec, they like very much to be
115
 
able to branch in-place so that they do not need to rebuild the whole
116
 
config to start new development.  (Though perhaps the real fix is to
117
 
make assembling a config simpler...)