These are the steps required to cut a SystemTap release.
Contents
Compile the release notes
Before you start, make sure that the NEWS file is actually current with the major changes, since this is the best base for forming the release notes. This is a good time to run "./AUTHORS.sh >AUTHORS" too, so we have proper credit.
It's easiest to get a template for the notes starting from previous SystemTapReleases. Here are the major sections to fill in:
- News blurb: 3-5 lines describing the highlights of this release. Reporters will work mostly just from this section. It may be best to do this part last, so you can summarize the rest of the release notes.
- Front-end changes: This is the general section for major changes, new command-line options, and even miscellaneous internal changes. These bulletted can come directly from the NEWS file.
- Script language changes: List the NEWS items that involve syntax changes in scripts.
- Tapset changes: List NEWS items for new probe points and tapset functions.
- Scripts examples: List the name and title of new examples. Use "git log --summary (old-release).. testsuite/systemtap.examples/" to see which files were created since the last release.
- Contributors: Get the list of names from "./AUTHORS.sh (old-release)..".
- Tested kernels: List the platforms that were used for testing this release.
- Known issues: Evaluate whether the previous issues are still valid, and add new ones if needed.
Bugs fixed: List the sourceware bug numbers and titles that were fixed since the last release. It's helpful to query bugzilla for Resolution:FIXED and "Only bugs changed between (day after last release) and Now."
Create the release in git
First, update the configure scripts. The files configure.ac and testsuite/configure.ac have the release version number near the top, which should be updated to the new release version. Save those changes and run autoconf. If autoconf gives errors about mismatched versions, then you may need to run autoreconf instead.
Then update the NEWS file. The top line should already say "What's new", and you can now add "in version X.Y".
Finally, update systemtap.spec. Near the top is a "Version:" line to update, and then add an entry to the "%changelog" section, following the previous entries as a template.
Commit all of these changes, and then tag them with "git tag -s release-X.Y". The "-s" signs the tag with your GPG key, which should be signed by at least one of the previous maintainers to keep up the "web of trust."
Don't push these changes or the tag to the public git repo yet -- it's easier to correct mistakes while everything is still local.
The last step before we go on is to create the source archive with "make dist-gzip".
Build the Fedora package
If you don't already have a Fedora account, then create one as described here. On your Fedora machine, you'll need to use yum to install "fedora-packager". Make sure that your certificate is saved as "$HOME/.fedora.cert", and then run fedora-packager-setup. Use "fedora-cvs systemtap" to checkout the release infrastructure in the current directory. (Make sure that this is done away from your systemtap git path!)
Within the systemtap directory from fedora-cvs, there is a "devel" directory which represents rawhide and F-## directories for each stable Fedora release. We usually update rawhide and the last two stable Fedoras with each stap release. Change to the devel directory first.
Upload the source archive you create from dist-gzip with "make new-sources FILES=/path/to/systemtap-X.Y.tar.gz", which will also update ".cvsignore" and "sources". Copy systemtap.spec from the git source tree. Now run "make local" to test the rpm build locally. If this succeeds, you're ready to create the official build.
Use CVS to commit "sources", ".cvsignore", and "systemtap.spec" to the fedora repository. If there are any patches from a Fedora minor update (which are hopefully in this new upstream release already), remove then from CVS too. Now run "make tag" to lock in the release version. (The tags are unique, so this is our point of no return!) Finally run "make build" to submit the build to koji.
Once the devel build is successful (or while it's running if you're feeling brave), repeat the above steps for the stable Fedora releases as well. The "make new-sources" step should tell you that the sources already exist, and then everything else is pretty much the same.
Special case: Fedora minor updates
Sometimes we want to update the Fedora packages without bothering with a full SystemTap release. In this case we shouldn't have to do new-sources; we can just provide a patch file and bump the spec accordingly. First, increase the number in the "Release:" header. Then add a new "PatchN: my-update.patch" line for each new patch with a unique number N. Apply each patch in the "%prep" section with "%patchN -p1". Finally, add an entry to the "%changelog" explaining the reason for patching, and proceed to test-tag-build as normal.
Push it out and announce it
Piece of cake, right? Now all that's left is to tell the world!
First get the public sources in order. Use a normal "git push" to update the public git HEAD, and then send the tag with "git push origin release-X.Y". Then upload the dist-gzip with scp to "sourceware.org:/sourceware/ftp/anonftp/pub/systemtap/releases/".
Next send out the release notes to systemtap@sourceware.org , and CC linux-kernel@vger.kernel.org and lwn@lwn.net .
Finally, update SystemTapReleases for the new version with links to the source archive, the git tag, and the archived release notes. If you like, you can update our Wikipedia page with the new version number too.