View source for How to do a Code Tour

== What is a code tour? ==

A code tour lists information about all of the bugs in [[Bugzilla]] that have been closed in the past week, or since the last code tour.  You can [http://dw-dev.dreamwidth.org/tag/code+tour view previous code tours] in <dwcomm>dw_dev</dwcomm> .

== How to make a code tour ==

First, find the ending date of the latest code tour post by [http://dw-dev.dreamwidth.org/tag/code+tour viewing the previous code tours]. Then, plug that date into the [http://hack.dreamwidth.net/dev/codetour/ Code Tour Template Generator], and click Generate. The script will automatically find all the RESOLVED FIXED bugs that have been modified since then, and present a text box with a pre-filled template, which you should copy and paste into a text editor on your computer.

There may be a few bugs that overlap with the previous code tour; those should be listed at the top, and can be deleted. (If any bugs from the previous code tour are in the list, but don't appear at the top, that means they've been updated since the last code tour and you should check them in case there have been any new patches.)

You should double-check the 'Category' and 'Patch by' fields to make sure they accurately reflect the bug (for example, sometimes the "patch by" field only includes who made the patch, but other people may have worked on it, especially in the arena of themes - and sometimes the assignee on the bug isn't the one who actually does the patch!), and then write a description for the bug. By default, the text "FILL IN" is pre-filled to make it easy to search for at the end and see if you missed anything, but if you prefer it blank, there's a ticky box on the first page of the generator that will do that for you.

Then, make an entry in <dwcomm>dw_dev</dwcomm> tagged "code tour".  The subject line should include the dates covered by the code tour, and the tour should be behind a &lt;cut&gt; tag to spare people's reading pages. The time to do these is generally the day of the <dwcomm>dw_news</dwcomm> update or the day before. (The day for this has in the past been Wednesday, or Monday, but is as always subject to change.)

== How to manually make a code tour ==

(You generally don't need to do this; this is just included for reference in case the generator fails. You should normally use the section above.)

First, get a link to a Bugzilla search from <dwuser>denise</dwuser> or by putting the start and end dates of the week into [http://bugs.dwscoalition.org/query.cgi?bug_status=RESOLVED&chfield=bug_status&chfieldfrom=2009-09-21&chfieldto=2009-09-27&query_format=advanced&resolution=FIXED this search form].  Then, put the information each bug into this example format:

 <b><a href="http://bugs.dwscoalition.org/show_bug.cgi?id=NNNN">Bug NNNN</a>:</b> Bug Title
 <b>Category:</b> What section of the site is this bug about?
 <b>Patch by:</b> <user name="username"> or submitter name
 <b>Description:</b> What problem does this bug solve, or what new feature does it add?

Then, make a post to <dwuser>dw_dev</dwuser> tagged "code tour".  The time to do these is generally Monday, so they can be included in the <dwuser>dw_news</dwuser> update.

Makes sure to double check the bug--sometimes the "patch by" field only includes who made the patch, but other people may have worked on it, especially in the arena of themes.

== How to make a Bugzilla search for a code tour ==

The base link is this: http://bugs.dwscoalition.org/buglist.cgi?&query_format=advanced&chfield=bug_status&bug_status=RESOLVED&resolution=FIXED

To that link, you want to add this to the end: <tt>&chfieldfrom=2010-03-02&chfieldto=Now</tt> where <tt>chfieldfrom</tt> has the day after the last code code tour on it (replace the <tt>2010-03-02</tt> with the appropriate date).  You can replace <tt>chfieldto</tt> with a date, too, if you like, but "Now" should work.

== Template Making Script ==

If you are comfortable with using Python on the command line, here is a script that can help you make a template with all the bugs in a CSV download of the week's bugs.  (You can find the CSV download link on the bottom of the search page.  You'll want to make sure to have these columns listed: Full Summary, Component, Assignee Realname, and Resolution.)

<source lang="python">#!/usr/bin/env python

# usage: python code_tour_template.py bugs-2009-09-15.csv

import csv, re, sys

def parse_assignment(assign):
    """Attempt to parse the assignment for the submitter's username.
    Use the full assignment field otherwise."""
    # [:username]
    match = re.search('\[\:([a-z0-9_]+)\]', assign);

    try:
        return '<user name="%s">' % match.group(1)
    except (IndexError, AttributeError):
        return assign

# Get the CSV file for the bugs
bugs_file = sys.argv[1]

bugReader = csv.DictReader(open(bugs_file))

# This is a template for a bug record
template_record = """
<b><a href="http://bugs.dwscoalition.org/show_bug.cgi?id=%(bug_id)s">Bug %(bug_id)s</a>:</b> %(title)s
<b>Category:</b> %(category)s
<b>Patch by:</b> %(patch_by)s
<b>Description:</b> FILL IN
"""

# For each row in the bug CSV file, put the appropriate variables into
# the template and print
for row in bugReader:
    replacements = { "patch_by": parse_assignment(row["assigned_to_realname"]),
        "bug_id": row["bug_id"],
        "category": row["component"],
        "title": row["short_desc"] }
    
    print template_record % replacements</source>

== How to do a Bugs (old and new) Tour ==

<a href="http://bugs.dwscoalition.org/show_bug.cgi?id=XX">Bug XX</a>: SUMMARY
Category:
Reported on DATE by <user name="NAME">
Severity and Priority:
Status: assigned to/unassigned
Description:</b>

Then, make a post to <dwuser>dw_dev</dwuser> tagged "code tour".  The time to do these is generally Monday, so they can be included in the <dwuser>dw_news</dwuser> update.

[[Category: Development]]

== How-to: a ten-step guide for first-timers ==

# join #dreamwidth[http://wiki.dwscoalition.org/wiki/index.php/IRC] and cry on people until they hold your hand
# spot a post in <dwuser>dw_volunteers</dwuser> requesting a code tour
# follow the link to the list of bugs/HTML template for the code tour
# open up the wiki page on how to do a code tour (well done! you're here!) and the handy Bugzilla list (both linked to from the handy HTML template)
# copy the template into your Post Entry box
# stare at it in dismay until you work out whether (and how) you want to try to be funny (that's the hard part!)
# write the pre-amble and closing notes, stick in the cut tag, open all of the bug descriptions at the Bugzilla link
# for each bug: 
#* confirm that the "patch by:" field matches the info given on the bug page (esp. in comments)
#* the commit message - generally in the final comment - forms a good basis for your summary in the "FILL IN"/Description space, but you'll probably want to flesh it out with details taken from the other comments
#* if you're confused about what it does, #dreamwidth is generally a good place to track down someone who can explain it to you so you can explain it to everyone else
#* and, for that matter, #dreamwidth is an excellent place to give running updates of the "ONE THIRD... ONE HALF... TWO THIRDS... but what if I get something WRONG and the WORLD ENDS... FIVE SIXTHS..." nature, and receive cheerleading in return!
# post your COMPLETED CODE TOUR to <dwuser>dw_dev</dwuser>
# gnaw on your nails until people start telling you it's okay: you have now achieved SUCCESS