|
11224.1.2
by Tim Penhey
Pretty much a rewrite. |
1 |
Branch merge proposals |
2 |
====================== |
|
3 |
||
4 |
The purpose of branch merge proposals are to indicate that the one branch |
|
5 |
should be merged into another branch. |
|
6 |
||
7 |
The branch to be merged is referred to as the "source branch", and the branch |
|
8 |
that is being merged into is referred to as the "target branch". |
|
9 |
||
10 |
In the early phases of development of this feature there was often a mixing of |
|
11 |
terms where the term "merge proposal" was used interchangably with "code |
|
12 |
review" which caused some confusion. |
|
13 |
||
14 |
- **Merge Proposal:** indicates that one branch should be merged with another. |
|
15 |
- **Code Review:** a discussion that takes place about the changes that would |
|
16 |
occur should the proposed merge happen |
|
17 |
||
18 |
A merge proposal may have a code reivew, but a code review always happens with |
|
19 |
respect to a merge proposal. |
|
20 |
||
21 |
||
22 |
Other Terms |
|
23 |
----------- |
|
24 |
||
25 |
Landing Targets |
|
26 |
These are the merge proposals related to the branch for which the branch |
|
27 |
that is being looked at is the source branch. It is called that due to the |
|
28 |
idea that the target branch is where the code intentds to 'land' or 'merge'. |
|
29 |
||
30 |
Landing Candidates |
|
31 |
These are the merge proposals that indicate the intent to merge with the |
|
32 |
branch being looked at. |
|
33 |
||
34 |
||
35 |
Creating a Merge Proposal |
|
36 |
------------------------- |
|
37 |
||
38 |
All merge proposals are created from the source branch using a method called |
|
39 |
``addLandingTarget``. |
|
40 |
||
41 |
>>> fooix = factory.makeProduct(name='fooix') |
|
42 |
>>> source_branch = factory.makeProductBranch(product=fooix) |
|
43 |
>>> target_branch = factory.makeProductBranch(product=fooix) |
|
44 |
>>> merge_proposal = source_branch.addLandingTarget( |
|
45 |
... registrant=source_branch.owner, |
|
46 |
... target_branch=target_branch) |
|
47 |
||
48 |
The bare minimum that needs to be specified is the person that is proposing |
|
49 |
the merge, the ``registrant``, and the branch that the registrant wants the |
|
50 |
branch to be merged into, the ``target_branch``. |
|
51 |
||
52 |
There are other optional parameters to initialize other merge proposal |
|
53 |
attributes such as the description, commit message or requested reviewers. |
|
54 |
||
55 |
It is considered good form to set at least one of the commit message or |
|
56 |
description. For very simple branches a commit message might be enough, but |
|
57 |
for non-trivial branches a description is often needed to describe the intent |
|
58 |
of the changes. |
|
59 |
||
60 |
||
61 |
States of a Merge Proposal |
|
62 |
-------------------------- |
|
63 |
||
64 |
During the life time of a merge proposal it will go through many states. |
|
65 |
||
66 |
Work in Progress |
|
67 |
The source branch is intended to be merged into the target, but the work has |
|
68 |
not yet been fully completed. |
|
69 |
||
70 |
Needs Review |
|
71 |
The work has been completed to the satisfaction of the branch owner, or at |
|
72 |
least some form of review of the change is being requested. |
|
73 |
||
74 |
Approved |
|
|
11224.1.4
by Tim Penhey
More on the states. |
75 |
The reviewer is happy with the change. |
76 |
||
77 |
Rejected |
|
78 |
The reviews is not happy with the change. |
|
79 |
||
80 |
Merged |
|
81 |
The source branch has been merged into the target. The branch scanner also |
|
82 |
sets the ``merge_revno`` of the merge proposal to indicate which revision |
|
83 |
number on the target branch has this merge in it. |
|
84 |
||
85 |
Superseded |
|
86 |
The intent of superseded proposals has changed somewhat over time, and needs |
|
87 |
some rework (bugs 383352, 397444, 400030, 488544) |
|
88 |
||
89 |
||
90 |
There are also some other states that are not yet in general use: |
|
91 |
||
92 |
Queued |
|
93 |
The merge proposal is queued for merging. The proposal will be part of some |
|
94 |
merge queue which a person or script (like tarmac) will process and do the |
|
95 |
merges. |
|
96 |
||
97 |
Merge Failed |
|
98 |
A script tried to merge the branch but it either failed to merge cleanly |
|
99 |
(had conflicts) or failed some tests as defined by the script. There is the |
|
100 |
facility to add a log file containing the failures here. |