File:  [NetBSD Developer Wiki] / wikisrc / Attic / workflow.mdwn
Revision 1.1: download - view: text, annotated - select for diffs
Sat Mar 16 22:11:47 2013 UTC (7 years, 7 months ago) by wiki
Branches: MAIN
CVS tags: HEAD
web commit by riz: Workflow and policies, adapted from localsrc/releng/pullups/POLICIES_AND_WORKFLOW

    1: # Releng workflow for pullups, and policies
    3: ## Overview
    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.
   14: ### Requirements
   16: * NetBSD
   17: * perl
   18: * localsrc
   20: (OK, so this should work on non-NetBSD.  You really want to go there?)
   22: ## General operating policies
   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.
   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 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.
   34: 3. Pullups need to conform to the guidelines given at
   35:    <>.
   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).
   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.
   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.
   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".
   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
   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.
   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.
   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)
   86: ## Workflow
   88: I ([[riz]]) will describe my working setup;  you may want to alter this to suit your
   89: needs.
   91: 1. Req is the ticketing system used to track the releases we're doing and it's
   92:    installed on in <code>/home/releng/req</code>.   The important tools are in
   93:    <code>/home/releng/req/bin</code>:
   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.
   99:    The current revs are:
  101:         5                    - NetBSD 5 queue
  102:         6                    - NetBSD 6 queue
  103:         pkgsrc            - Current pkgsrc branch
  105:    Get the "req" commands set up to your liking.  They are run on 
  106:, 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
  111:         ssh $(basename $0) $*
  113:    ...and link it to the various commands I wish to run, such as "5-req".
  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.
  122:    I use:  <code>/usr/releng</code> and <code>~/releng</code> respectively.  Whatever you choose,
  123:    make sure you adapt the instructions.
  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>.
  131: 4. Check out your source trees with the proper branch tags.  
  133:         $ cvs -q -d co -P -r<BRANCH> src xsrc
  135:    (I generally rename these to "src6" and "xsrc6" (etc), and maintain
  136:     "src51" "src52"  and "src60" as well.  YMMV)
  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:
  142:         $ 6-q
  143:         <lots of output;  I want to work on 9999>
  144:         $ 6-req take 9999
  146: 6. Get the text of the ticket.
  148:         $ 6-req show 9999 > 9999   # put it in a file "9999" in /usr/releng
  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:
  156:         $ ./r-start riz 9999 < 9999    # script wants the commit email on stdin
  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. 
  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.
  173: 8. Assuming all is well, run the 'r-pullup' script FROM THE TOP LEVEL
  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.
  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. 
  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.
  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.
  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.
  205: 11.  Commit the changes file.  In the log message, note which ticket you
  206:      applied.
  208: 12.  Reply to the requestor, and close the ticket.
  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](, to see if there were any
  213: problems introduced, and correct them.

CVSweb for NetBSD wikisrc <> software: FreeBSD-CVSweb