1: # Releng workflow for pullups, and policies
2:
3: ## Overview
4:
5: This is one possible releng workflow. Yours, once you've
6: settled in, may differ. The goal is to illustrate the process of going
7: from a pullup request (generally formatted as a number of commit
8: emails, or links to commit emails, with diffs when the original
9: commits don't apply cleanly to the branch) to a completed pullup. Much
10: of the information in here is taken (often verbatim) from an email I (riz)
11: received from jmc@ when I joined releng in 2005, and has been updated
12: somewhat to reflect recent situations.
13:
14: ### Requirements
15:
16: * NetBSD
17: * perl
18: * localsrc
19:
20: (OK, so this should work on non-NetBSD. You really want to go there?)
21:
22: ## General operating policies
23:
24: 1. You do not process your own pullup requests. This is for sanity so another
25: set of eyes sees it. This is fairly major deal and we all need to abide by
26: it.
27:
28: 2. All pullup requests must come from an active developer. If you're not sure
29: if the person is a developer, check the People page on netbsd.org or ask
30: them. If they aren't a developer, kick it back to them (and close out
31: the request) and politely explain this must come through a developer. See
32: item 7 below for how to close a request.
33:
34: 3. Pullups need to conform to the guidelines given at
35: <http://www.netbsd.org/developers/releng/pullups.html>.
36: Properly formatted ones should be worked and improper ones can be worked
37: at your own discretion/mood (or kicked back to the sender for fixes).
38:
39: 4. The burden of basic testing (to verify the change is correct on the
40: branch for which it is requested) falls upon the requestor. In
41: those cases where it is clear the requestor has requested large
42: changes without adequate testing, don't be afraid to push back
43: politely. It's almost always easier to fix problems before
44: committing on the branch than it is to back out bad changes later.
45:
46: 5. Pullups should, when possible, be processed using the centrally-maintained
47: scripts in localsrc/releng/pullups/scripts, to keep the format as
48: standard as possible, and to minimize human error. It is not always
49: possible to use the scripts for all pullups; when a patch is required,
50: please conform as much as possible to standard formats for the
51: changelist (appended to doc/CHANGES-<rev>) and for the commit message.
52: Very large, intrusive, and non-automated pullups often require a lot
53: of manual intervention. If special circumstances arise where it's not
54: possible (or a ridiculous amount of work is required) to follow
55: convention, your best bet is to ask the other members of releng for
56: a consensus on how to proceed.
57:
58: 6. Changelist entries, even when generated by the scripts, should be edited
59: for brevity. No more than two or three lines per change in the usual
60: case, and please try to make it descriptive of the effect of the change.
61: In some cases, you may need to ask for help from the requestor if
62: you don't fully understand the effect yourself. Use complete
63: sentences, proper capitalization, note PRs in the format "PR#XXXX", and
64: SAs (when we have them) as "SA#XXXX".
65:
66: 7. When replying back to the pullup requestor, include their CHANGES entry
67: back in the email and then close out the request by adding
68:
69: *REQ: resolve
70: to the email so req closes the ticket out. (note that any additional emails
71: referencing that ticket number will re-open it, so be careful if someone
72: replies and says "thanks" back to the pullup list). Note that you can
73: use req directly to close a ticket without sending email. See item 1 in
74: the workflow section below.
75:
76: 8. If a pullup doesn't work, needs more info, etc make sure to put it in the
77: "stalled" state so it's obvious it's been looked at but more work needs to
78: be done. (Also, when we're about to cut a minor release all open requests
79: that don't apply are stalled). Please make sure you note *why* a change
80: was stalled; when unstalling, note reasons as well.
81:
82: 9. In general, take ownership of a request using req before working on it,
83: so effort isn't duplicated. (With very straightforward, quick-to-handle
84: requests, this isn't strictly necessary, but it's good practice anyway)
85:
86: ## Workflow
87:
88: I ([[riz]]) will describe my working setup; you may want to alter this to suit your
89: needs.
90:
91: 1. Req is the ticketing system used to track the releases we're doing and it's
92: installed on releng.netbsd.org in <code>/home/releng/req</code>. The important tools are in
93: <code>/home/releng/req/bin</code>:
94:
95: <rev>-q - Show the current queue
96: <rev>-req - The main command processor to stall, resolve, etc
97: a request. Run <rev>-req -? for examples.
98:
99: The current revs are:
100:
101: 5 - NetBSD 5 queue
102: 6 - NetBSD 6 queue
103: pkgsrc - Current pkgsrc branch
104:
105: Get the "req" commands set up to your liking. They are run on
106: releng.netbsd.org, and may either be run directly there, or via ssh.
107: What I generally do is set up a script in my path on the machine I
108: use for releng work that looks like this:
109: #!/bin/sh
110:
111: ssh releng.netbsd.org $(basename $0) $*
112:
113: ...and link it to the various commands I wish to run, such as "5-req".
114:
115: 2. Create two directories: one for source trees (I like to keep one
116: for each supported branch checked out, to speed things up, but if space
117: is at a premium, you may want to adjust this) and one for the
118: files generated by the releng scripts. **NOTE**: the directory where
119: the generated files go is emptied every time the r-start script is
120: run, so DON'T put anything you might need later in there.
121:
122: I use: <code>/usr/releng</code> and <code>~/releng</code> respectively. Whatever you choose,
123: make sure you adapt the instructions.
124:
125: 3. The <code>r-start</code> script (<code>localsrc/releng/pullups/scripts/r-start</code>) is the
126: one which actually gets called. It needs perl, and it needs to be
127: edited to set the values of <code>RELENG_TMPDIR</code> and <code>RELENG_SCRIPTS</code> to wherever
128: you locate them. I like to make a copy of <code>r-start</code> in my <code>/usr/releng</code>
129: dir and run it from there as <code>./r-start</code>; you may want it in your <code>$PATH</code>.
130:
131: 4. Check out your source trees with the proper branch tags.
132:
133: $ cvs -q -d cvs.netbsd.org:/cvsroot co -P -r<BRANCH> src xsrc
134:
135: (I generally rename these to "src6" and "xsrc6" (etc), and maintain
136: "src51" "src52" and "src60" as well. YMMV)
137:
138: 5. Use (for example) "6-q" to list the queue for pullup-6; Take ownership
139: of the ticket you're going to work on. Let's use "9999" as the ticket
140: number:
141:
142: $ 6-q
143: <lots of output; I want to work on 9999>
144: $ 6-req take 9999
145:
146: 6. Get the text of the ticket.
147:
148: $ 6-req show 9999 > 9999 # put it in a file "9999" in /usr/releng
149:
150: 7. Find the login name of the developer *requesting the pullup* (not
151: necessarily the one who made the original change, though they're often
152: the same). Let's say it's me (riz). Assuming this is a standard pullup
153: (one or more commit emails, no patches necessary), use 'r-start' to
154: generate the working files:
155:
156: $ ./r-start riz 9999 < 9999 # script wants the commit email on stdin
157:
158: This generates a number of files in RELENG_TMPDIR (~/releng, in my case).
159: Look at these files; there's various useful stuff in there. Usually,
160: what you'll need are three files: cl, r-pullup, and r-commit. "cl" is
161: the changelist file which gets appended to doc/CHANGES-<rev>; it will
162: need to be edited for whitespace and content, but should have the basic
163: framework there. "r-pullup" is a script which uses 'cvs update -j' to
164: apply the changes to the branch, and "r-commit" performs the commit and
165: has the log message. You should check these over, but often they don't
166: require editing.
167:
168: ***NOTE***: with the current version of the scripts,
169: revisions can get pulled up out of order. If there are many commit
170: emails in the pullup request, you should edit r-pullup to make sure
171: that the ordering is correct, otherwise you may get unnecessary conflicts.
172:
173: 8. Assuming all is well, run the 'r-pullup' script FROM THE TOP LEVEL
174: SOURCE DIRECTORY OF THE BRANCH YOU'RE APPLYING IT TO. If this is
175: for netbsd-5, I would cd to "/usr/releng/src5" and run it there.
176: For netbsd-5-1, "/usr/releng/src51", etc. Make sure your sticky tags are
177: correct! Pullups in xsrc need to be treated separately; they're fairly
178: rare, so just keep an eye out for them, and handle them as seems
179: appropriate from what is generated in the r-pullup script. The only
180: exception is that r-pullup doesn't generate the "xsrc" prefix in
181: the "cl" file, and you will need to add that yourself.
182:
183: You need to observe the output of r-pullup; if there are conflicts,
184: you should bounce the request, clean up your src dir (a manual process,
185: sorry) and stall the ticket until the requestor provides a patch.
186:
187: **NOTE**: if the pullup request says that it doesn't apply cleanly,
188: it should include a patch. These need to be handled on a case-by-case
189: basis, but often it's enough to run 'r-start' to get the files
190: created to form a baseline; edit them as appropriate, but instead of
191: running the r-pullup script, just apply the patch instead. Be sure to
192: add "via patch" to revisions listed in the commit message and CHANGES
193: entry.
194:
195: 9. Assuming there are no conflicts (you may want to run a 'cvs -q update -dP'
196: to check, especially early on), you can commit the changes. In the
197: basic case, it's just a matter of running the "r-commit" script.
198: If you commit anything by hand, make sure the commit log has a
199: well-formed message.
200:
201: 10. Append the changes file ("cl") to doc/CHANGES-<rev>. For example,
202: doc/CHANGES-5.2 is the currently-in-use log for post-5.1 but pre-5.2
203: changes that we're working on. Each branch has a different file.
204:
205: 11. Commit the changes file. In the log message, note which ticket you
206: applied.
207:
208: 12. Reply to the requestor, and close the ticket.
209:
210:
211: That's basically it; if you perform a complicated pullup (or series of them),
212: you may want to keep an eye on the [autobuild](http://releng.netbsd.org/cgi-bin/builds.cgi), to see if there were any
213: problems introduced, and correct them.
CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb
![[BACK]](/icons/back.gif){kind=icon}
Return to workflow.mdwn CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [NetBSD Developer Wiki] / wikisrc