Preparing the Version History

First, be sure to read the Version History Policy and FAQ. This spells out the policy for the version history and explains a big part of your task at release time: finding missing entries.

Of course, you can't finalize the version history until the code-freeze for the release and the source is tagged. So, in practice, you'll have to coordinate with the real release wrangler to make sure you're looking at the right diff.

Once you've got the official release tag (or the build tag that's going to become the official tag), here's what you do:

  1. The version history is in the doc/ tree in the git reposictory. Inside doc, you'll need to edit version-history/X-Y.history.tex where X-Y matches the release series you're working from (e.g. 7-0).
  2. Run git log between the last release and the current release from the same series: 
    git log -p V7_0_1..V7_0_2 > 7.0.2-diff
    If the V7_0_2 tag doesn't exist yet, use the appropriate build tag, e.g. BUILD-V7_0_2-branch-2008-6-9.
  3. Go through the saved output (e.g. 7.0.2-diff) and make sure everything in there that should be documented has a corresponding entry in the version history. The following is some git scripting to help in this. 
    git --no-pager log origin/V7_9_1-branch --not V7_9_0 | grep -o '#[0-9]\+' | sort -u | sed 's/^.//' > all-tickets
git --no-pager log origin/V7_9_1-branch --not V7_9_0 -- doc/ | grep -o '#[0-9]\+' | sort -u | sed 's/^.//' > doc-tickets
diff -u doc-tickets all-tickets | grep '^+[0-9]'
    The script above produces a list of tickets that have been incorporated into the 7.9.1 and that are not in 7.9.0, and that do not have commits under doc/ As such, it also includes commits in 7.8.x and also commits that do not require version history. It does not catch commits that should have ticket numbers and do not. It is useful as a place to start with the version history preparation.
  4. If you find parts of the diff that should be documented which are missing, make a list of the missing entries and who committed the changes.
  5. A development release will normally have several fixes from the concurrent stable branch, so it should have a version history item that indicates this. Something like "This release contains all bug fixes from HTCondor version 7.6.2." in the 7.7.0 version history.
  6. Once you've gone through the entire diff, email your list of missing entries to condor-team@cs.wisc.edu for public humiliation and so that people know how much they owe to the version history pizza fund (see the policy/FAQ). You can either add the missing entries yourself, or get the guilty parties to do it.

That's the whole task. However, give yourself at least a day to do it, since the diff can be huge and this is a time consuming process. Once you're done, notify the "real" release wrangler so they know when it's safe to publicly release the manual.