Differences between revisions 58 and 59
Revision 58 as of 2018-06-08 20:21:35
Size: 8409
Editor: FChE
Revision 59 as of 2020-06-11 14:24:57
Size: 8430
Editor: FChE
Deletions are marked like this. Additions are marked like this.
Line 15: Line 15:
'''Increment Copyright years in messages''' (session.cxx, staprun/common.c, stapdyn/stapdyn.cxx) if needed. '''Increment Copyright years in messages''' (session.cxx, staprun/common.c, stapdyn/stapdyn.cxx, stapbpf/stapbpf.cxx) if needed.

These are the steps required to cut a SystemTap release.

Check the build

Run "make update-po" in a top-level build tree. This may update several po/* files in the source tree. Commit those changes.

Update the AUTHORS file with AUTHORS.sh.

Check the whole source tree for the PRERELEASE marker. Yes, emacs, not vi.

git grep -Oemacs PRERELEASE

Increment Copyright years in messages (session.cxx, staprun/common.c, stapdyn/stapdyn.cxx, stapbpf/stapbpf.cxx) if needed.

Set the productnumber in doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml to match the release number.

Update the documentation in the source tree using "./scripts/update-docs".

Regenerate the examples index in "testsuite/systemtap.examples".

Make sure that the NEWS file is actually current with the major changes, since this is the best base for forming the release notes.

Run a fuller-than-usual build:

configure --enable-dejazilla --enable-testapps=all
make rpm  # on several OS generations, for dependency/build-tool differences
make all install
sudo make installcheck

The testapps part is especially important if sys/sdt.h changed from the last version, since other applications compile against that now. Regressions in compilability / performance in these sdt.h client apps should be avoided.

The remote functionality requires a bit of manual setup for testing, as for each host you must have both an automated ssh connection (e.g. via kerberos or ssh pubkeys) and an appropriate build environment, locally or using a compile server. With those conditions met, you can run an installcheck with TESTREMOTES as a comma-delimited list of hosts, e.g. "make installcheck RUNTESTFLAGS=remote.exp TESTREMOTES=foo,bar,baz"

Compile the release notes

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. Even better, do a "git log" on the tapset/ directory.
  • Script 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. If an associated '.meta' file exists for the new example, it should contain a description. Include the examples URL and current number of examples.

  • Contributors: Get the list of names from "./AUTHORS.sh (old-release)..". Specially welcome new contributors, found with "git diff (old-release) AUTHORS".
  • 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." (To just see the bug number and the summary for each bug, hit the "Change Columns" link and just look at the "Summary".) You may need to edit the descriptions a bit. Check also CVE's and bugzilla.redhat.com.

Create the release in git

Check that the configure and .spec files have the correct version number. The .spec should also have an appropriate %changelog entry with the current date, and a link to the SystemTapReleases wiki page (so people can find/read the release notes based on the rpm %changelog.) Add the release date to the top of NEWS.

Tag the tree 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."

Create the final source archive with "make dist-gzip", and sign it: gpg -b systemtap-X.Y.tar.gz, which will result in a .asc file.

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 source archive and its signature with scp to "sourceware.org:/sourceware/ftp/anonftp/pub/systemtap/releases/".

If something goes dramatically wrong with building this tarball during your own or fedora builds, it will be necessary to create a new minor version tag, tarball, and perhaps a mini-release-note.

Build the Fedora package

Upstream docs: https://fedoraproject.org/wiki/Using_Fedora_GIT, http://fedoraproject.org/wiki/Package_update_HOWTO.

Upload the source archive you create from dist-gzip with "fedpkg new-sources /path/to/systemtap-X.Y.tar.gz", which will also update ".gitignore" and "sources". Copy systemtap.spec from the git source tree. Consider merging fedora-only changes committed to the tree. Now run "fedpkg local" to test the rpm build locally. If this succeeds, you're ready to create the official build. If it fails, and a minor fedora-only spec-file patch makes it go, make it so. If something systemic is wrong requiring a source tarball respin, see above about a new tag, etc.

Use "fedpkg ci; fedpkg push" to commit "sources", ".gitignore", 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 git too. Finally run "fedpkg build" to submit the build to koji.

Once the devel build is successful (or while it's running if you're feeling brave), "fedpkg switch-branch" to one of the release-track fedoras. Run "git merge devel" to do all the equivalent of what you did for devel. "fedpkg ci; fedpkg tag; fedpkg push; fedpkg build".

In each release-track branch "fedpkg update" must be run to submit the package to bodhi once the build is finished. (You don't have to run "fedpkg update" for rawhide, since packages there get pushed automatically.)

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!

Regenerate the documentation on the sourceware web site using "./scripts/update-htmldocs".

Recheck the release notes one last time, in case of any last-minute closed PRs, added samples, NEWS blurbs, new AUTHORS. Next send out the release notes to systemtap@sourceware.org , and CC linux-kernel@vger.kernel.org and lwn@lwn.net , with a format-preserving mailer. Watch out for word-wrap.

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.

Formally begin the next release's development cycle by bumping the version numbers. The following files need to be updated to the next version:

  • configure.ac: in the AC_INIT macro
  • testsuite/configure.ac: in the AC_INIT macro
  • doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml: the <edition> and <productnumber> tags

  • systemtap.spec: the 'Version:' line. If you like, add a placeholder entry to the "%changelog" section, following the previous entries as a template.
  • NEWS: create a new "What's new in ... PRERELEASE" line in the NEWS file.

Save those changes and run autoconf. If autoconf gives errors about mismatched versions, then you may need to run autoreconf instead.

None: SystemTapReleaseGuide (last edited 2020-06-11 14:24:57 by FChE)