Writing code summaries

From Genecats
Jump to navigationJump to search

This page summarizes the task of aggregating code summaries from the engineers, placing them in our genecats repo and wikis, and announcing the changes to the team. There is also a page aimed at the engineers for writing the summaries (https://genomewiki.ucsc.edu/genecats/index.php?title=Code_summary).

At a high level, what happens is: when the Build Meister builds the release candidate, each engineer (really, anyone who checked in code that week) receives an email with a list of everything they checked in and a request to summarize their commits and send them to the writer. You write them up and post them at our two locations. This writer role can be changed by the build meister in the final build scripts.

Here is an outline of the process:

1) Emails arrive after the final beta build (so this is only every 3 weeks -the week we test beta) A good tip is to create a gmail filter for the emails, something like matches: subject:("Code summaries" OR "do git summaries") Do this: Skip Inbox, Apply label "code".

2) The email tells everyone they should send you summaries by Tues 5pm -but Tuesday morning I send a "Reminder code summaries are due end of today." mainly to spark earlier arrivals -some people email them on Monday. Sometimes additional reminders are needed.

3) There is also another email with the subject "Code summaries for v410 are expected from...." with the names of everyone who committed code that week. Some people find that helpful for keeping track of the summaries, but you also have the individual emails.

4) Begin to aggregate all of the code summaries in the following format, note that often you will have to wordsmith the answers and make tweaks:

CODE (Which represents all kent code changes)

  • Made change one (#49604). Brian
  • Made change two (#39595). Chris
  • etc

DATA

  • Created track one (#94865). Angie
  • Released assembly two (#98569). Galt

Note that whenever possible we want to add the RM number on there.

5) After everyone has given you the code summaries you can feel free to rearrange the order, usually by putting the most prominent code changes toward the top. Ordering the code reviews will be helpful for future Progress Report writing, to see the most significant code changes toward the top.

6) Once you have your summaries written up, you will want to update the two following files:

  • ~/genecats/builds/versions.html
  • ~/genecats/builds/versions-list.html

As well as create a new file corresponding to the current version, e.g. version 1337:

  • ~/genecats/builds/versions-all/v1337.html

The fastest way is to copy a previous version to get the skeleton, and just delete all the list items while updating the version number and calendar dates. Then add your summaries over.

7) Once that is done, you can run the following line to turn all of your RM hashes (e.g. (#596)) into links, using v416 as an example:

cat v416.html | sed -e 'sZ(#[0-9]*Z(<a href="http://redmine.soe.ucsc.edu/issues/&" target="_blank">&</a>Z' | sed -e 'sZ/(#Z/Z' | sed -e 's/(#/#/' > v416.html

8) Commit all your changes, and run "make install" from the ~/genecats directory

9) Add a condensed version of the summaries (only things relevant to users and mirror operators) to our external wiki page: http://genomewiki.ucsc.edu/index.php/Genome_Browser_Software_Features

10) Verify that the summaries made it out OK: https://genecats.gi.ucsc.edu/builds/versions.html

11) Write an email to browser staff with the code summaries. You can find many examples searching your inbox for "subject:Check out what is in"

Retrieved from "https://genomewiki.ucsc.edu/genecats/index.php?title=Writing_code_summaries&oldid=6303"