Annotation of wikisrc/workflow.mdwn, revision 1.1
1.1 ! wiki 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