Difference between revisions of "How to do a Code Tour"

From Dreamwidth Notes
Jump to: navigation, search
(How to make a code tour)
(branch name changed)
 
(33 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
== What is 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.  You can view previous code tours in <dwcomm>dw_dev</dwcomm> [http://dw-dev.dreamwidth.org/tag/code+tour here].
+
A code tour lists information about all of the issues that have been closed 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 ==
 
== How to make a code tour ==
  
First, get a link to a Bugzilla search from <dwuser>denise</dwuser>. Then, put the information each bug into this example format:
+
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. (Using the "From the date of the last code tour" option requires the repository to have been updated - it's best to double-check manually so you don't duplicate effort.) The script will automatically find all issues and pull requests that have been closed since that date, and present a text box with a pre-filled template, which you should copy and paste into a text editor on your computer. '''Note that this is different to the old Bugzilla code-tour generator''', which only compiled bugs marked RESOLVED FIXED: you need to check each item manually to make sure that you're not including anything that would in Bugzilla have been marked e.g. RESOLVED DUPLICATE or RESOLVED WON'T FIX.
  
<b><a href="http://bugs.dwscoalition.org/show_bug.cgi?id=NNNN">Bug NNNN</a>:</b> Bug Title
+
There may be a few bugs that overlap with the previous code tour; you will need to cross-reference with the last code tour, because bugs are listed in ascending numerical order not chronologically by date closed.
<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.
+
You should double-check the 'Patch by' field 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. The text "FILL IN" is pre-filled to make it easy to search for at the end and see if you missed anything. The 'Category' field is legacy from Bugzilla and does not need filling in manually.
  
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.
+
For preference, make a note of any issue that should be documented (generally changes in behaviour or functionality) and [https://docs.google.com/forms/d/1wsOq8TIdV7v3FrddsKSMze9DnKRIb1o20Jxx2juKrOM/viewform record it in the documents management system].
  
== Template Making Script ==
+
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.
  
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.
+
When you've finished this, grab someone with commit access to the repositories in question, tell them what the latest issue included in the code tour was (preferably with link!), and get them to update the pointer (so that the tool offers the correct date for the "From the date of the last code tour" option). The committer will need to run the following commands:
  
<source lang="python">#!/usr/bin/env python
+
  git checkout code-tour
 +
  git merge --no-ff main
  
# usage: python code_tour_template.py bugs-2009-09-15.csv
+
== How to manually make a code tour ==
  
import csv, re, sys
+
(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.)
  
def parse_assignment(assign):
+
First, get a list of closed issues and pull requests by filtering [https://github.com/dreamwidth/dw-free/issues?utf8=%E2%9C%93&q=is%3Aclosed+ the list of closed issues] by date (note that this link gives you closed issues in the dw-free repository only, and it may be appropriate to also include issues from dw-nonfree). Then, put the information for each issue into this example format:
    """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:
+
<b><a href="https://github.com/dreamwidth/dw-free/issues/NNNN">Issue NNNN</a>:</b> Bug Title (<a href="https://github.com/dreamwidth/dw-free/pulls/MMMM">pull request</a>)
        return "".join(['<user name="', match.group(1), '">'])
+
<b>Category:</b> What section of the site is this bug about?
    except (IndexError, AttributeError):
+
<b>Patch by:</b> <user name="username" site="github"> or submitter name
        return assign
+
<b>Description:</b> What problem does this bug solve, or what new feature does it add?
  
# Get the CSV file for the bugs
+
Then, make a post to <dwuser>dw_dev</dwuser> tagged "code tour". The time to do this is generally the day before or of a code push.
bugs_file = sys.argv[1]
+
  
bugReader = csv.DictReader(open(bugs_file))
+
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.
  
# This is a template for a bug record
+
== How-to: a ten-step guide for first-timers ==
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
+
# join [[IRC|#dreamwidth]] and cry on people until they hold your hand
# the template and print
+
# spot a post in <dwuser>dw_volunteers</dwuser> requesting a code tour
for row in bugReader:
+
# follow the link to the list of bugs/HTML template for the code tour. <strong>It's worth checking the previous code tour to make sure you don't have any duplicates, especially if you have more than 15 bugs to write up.</strong>
    replacements = { "patch_by": parse_assignment(row["assigned_to_realname"]),
+
# open up the wiki page on how to do a code tour (well done! you're here!) and the handy issues list (both linked to from the handy HTML template)
        "bug_id": row["bug_id"],
+
# copy the template into your Post Entry box.
        "category": row["component"],
+
# stare at it in dismay until you work out whether (and how) you want to try to be funny (that's the hard part!)
        "title": row["short_desc"] }
+
# write the pre-amble and closing notes, stick in the cut tag, fill in the subject with "Code tour: date--date", open all of the bug descriptions at the issue link
   
+
# for each bug:
    print template_record % replacements</source>
+
#* 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
 +
#* sometimes they have been kind and left a sentence or three labeled "CODE TOUR"
 +
#* 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>, making sure to tag it with "code tour"
 +
# gnaw on your nails until people start telling you it's okay: you have now achieved SUCCESS
  
 
[[Category: Development]]
 
[[Category: Development]]

Latest revision as of 19:58, 22 October 2022

What is a code tour?

A code tour lists information about all of the issues that have been closed since the last code tour. You can view previous code tours in [info]dw_dev .

How to make a code tour

First, find the ending date of the latest code tour post by viewing the previous code tours. Then, plug that date into the Code Tour Template Generator, and click Generate. (Using the "From the date of the last code tour" option requires the repository to have been updated - it's best to double-check manually so you don't duplicate effort.) The script will automatically find all issues and pull requests that have been closed since that date, and present a text box with a pre-filled template, which you should copy and paste into a text editor on your computer. Note that this is different to the old Bugzilla code-tour generator, which only compiled bugs marked RESOLVED FIXED: you need to check each item manually to make sure that you're not including anything that would in Bugzilla have been marked e.g. RESOLVED DUPLICATE or RESOLVED WON'T FIX.

There may be a few bugs that overlap with the previous code tour; you will need to cross-reference with the last code tour, because bugs are listed in ascending numerical order not chronologically by date closed.

You should double-check the 'Patch by' field 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. The text "FILL IN" is pre-filled to make it easy to search for at the end and see if you missed anything. The 'Category' field is legacy from Bugzilla and does not need filling in manually.

For preference, make a note of any issue that should be documented (generally changes in behaviour or functionality) and record it in the documents management system.

Then make an entry in [info]dw_dev tagged "code tour". The subject line should include the dates covered by the code tour, and the tour should be behind a <cut> tag to spare people's reading pages. The time to do these is generally the day of the [info]dw_news update or the day before.

When you've finished this, grab someone with commit access to the repositories in question, tell them what the latest issue included in the code tour was (preferably with link!), and get them to update the pointer (so that the tool offers the correct date for the "From the date of the last code tour" option). The committer will need to run the following commands:

 git checkout code-tour
 git merge --no-ff main

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 list of closed issues and pull requests by filtering the list of closed issues by date (note that this link gives you closed issues in the dw-free repository only, and it may be appropriate to also include issues from dw-nonfree). Then, put the information for each issue into this example format:

<a href="https://github.com/dreamwidth/dw-free/issues/NNNN">Issue NNNN</a>: Bug Title (<a href="https://github.com/dreamwidth/dw-free/pulls/MMMM">pull request</a>)
Category: What section of the site is this bug about?
Patch by: <user name="username" site="github"> or submitter name
Description: What problem does this bug solve, or what new feature does it add?

Then, make a post to [info]dw_dev tagged "code tour". The time to do this is generally the day before or of a code push.

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: a ten-step guide for first-timers

  1. join #dreamwidth and cry on people until they hold your hand
  2. spot a post in [info]dw_volunteers requesting a code tour
  3. follow the link to the list of bugs/HTML template for the code tour. It's worth checking the previous code tour to make sure you don't have any duplicates, especially if you have more than 15 bugs to write up.
  4. open up the wiki page on how to do a code tour (well done! you're here!) and the handy issues list (both linked to from the handy HTML template)
  5. copy the template into your Post Entry box.
  6. stare at it in dismay until you work out whether (and how) you want to try to be funny (that's the hard part!)
  7. write the pre-amble and closing notes, stick in the cut tag, fill in the subject with "Code tour: date--date", open all of the bug descriptions at the issue link
  8. 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
    • sometimes they have been kind and left a sentence or three labeled "CODE TOUR"
    • 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!
  9. post your COMPLETED CODE TOUR to [info]dw_dev, making sure to tag it with "code tour"
  10. gnaw on your nails until people start telling you it's okay: you have now achieved SUCCESS