Annotation of wikisrc/releng/workflow.mdwn, revision 1.1

1.1     ! riz         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