-
Notifications
You must be signed in to change notification settings - Fork 49
Release Process
This page documents the process that is currently used to prepare a new libtrace release.
Branch 'develop' into a new RC branch before starting. This will allow others to keep adding features to develop without interfering with your release. Any fixes that you make over the course of testing the release candidate will go back to this branch for now.
git checkout -b rc-<version number>
The existing ChangeLog page should serve as a pretty good example of what is expected. Typically we split the changes into three sections: New Features, Bug Fixes and Improvements.
New Features usually describes new trace formats, API functions, tools or protocols that have been added in this release.
Bug Fixes describes the bugs that were present in the previous release but have now been fixed in this one. Bugs that were both introduced and fixed since the last release shouldn't be included.
Improvements describes changes that have made some existing non-broken behaviour better, e.g. performance improvements, new configuration options for tools, better error reporting/handling, etc.
It's also nice to add a line thanking anyone outside of the author team who has contributed patches or reported major bugs.
For the release date, put "coming soon" for now. You can go back and put the correct date in once the new release has been pushed out.
The AUTHORS file currently lists all of the people who have contributed some code towards libtrace. If we accepted any patches from anyone since the last release, make sure that their name is included in this file.
The version number only appears in two files in the libtrace source tree. One is the README on the first line. The other is configure.in where it appears in two places: in the AC_INIT line and the variables LIBTRACE_MAJOR, LIBTRACE_MID and LIBTRACE_MINOR immediately below the AC_INIT line. Update the version number accordingly in both files.
Don't worry that we appear to be creating an extraneous branch on the public repository. We'll remove it once we're done, but it is nice to have the rc branch easily available via HTTP during the testing process.
Check that the rc branch builds and runs on various stock installs of the latest released versions of all of the operating systems and distros that we nominally support.
Specifically, we should test on:
- Fedora
- FreeBSD
- Mac OS X
- Debian testing
- Ubuntu (not just the LTS version)
- OpenBSD (less important, but nice to still support)
My typical strategy for each test:
- Spin up a VM by installing the testing OS from an ISO. Give your user the ability to gain root privileges via sudo.
- Use the built-in package management system to install the various requirements for libtrace / libwandio. Make sure you install the development version of the dependent libraries. Typical dependencies that might be missing: g++, flex, bison, automake, autoconf, libtool, libpcap, zlib, libssl.
- Install libwandio -- just wget the latest release from the WAND website.
- Git clone libtrace.
- Checkout your rc branch.
- Bootstrap, configure, make.
- Keep an eye out for any warnings during the build -- ideally we want no warnings if we can avoid them. Compilers tend to get stricter with each new OS release, so new warnings often appear during this step. Don't worry about any warnings from the lexer code though -- the code is auto-generated so there's not much you can do.
- Fix any build errors or warnings that appeared during the test. If you made any changes, repeat the build step until you get a clean build.
- sudo make install.
- Go into the test/ directory within the libtrace source tree.
- make clean; make.
- If you are on FreeBSD: install bash and create a symlink from /bin/bash to wherever bash actually ended up being installed.
- Run ./do-tests.sh -- this tests libtrace's ability to read, write and convert between various file formats. All of the tests (except for bzip2 and lzma autodetection, depending on whether you built libwandio with support for these compression formats) should pass on every system -- you'll need to investigate and fix any failures.
- Run ./do-tests-parallel.sh -- this tests the parallel API when reading from files. All of the tests should pass on every system -- you'll need to investigate and fix any failures.
- Run sudo ./do-live-tests.sh -- this tests reading packets using a small selection of the live formats. These tests should work on Linux systems but you'll get some failures on anything else (specifically, pcapint: should work on any system but int: and ring: are Linux-specific).
- If on !Linux, also try testing the bpf: format by running: sudo tracertstats -i 1 bpf:
- Commit any changes that you had to make to get a clean build and pass all relevant tests back to the rc branch. Make sure you configure your git user name and email on the VM first!
- Don't delete your VM until you've finished the release -- it is possible you might make a change on one system that you want to double check on another.
Use tracertstats to perform at least a cursory test that libtrace can capture from DPDK without segfaulting or immediately failing.
Again, use tracertstats to perform at least a cursory test that libtrace can capture from DAG without segfaulting or immediately failing.
It would also be worth ensuring that nDAG still works, provided you have access to the code that can generate nDAG output.
Pull in any changes that were made during testing and make sure you haven't broken anything obvious :)
make dist
Copy the tarball to a couple of the testing VMs and make sure you can build directly from the tarball
Files can get left out of the tarball (e.g. someone forgot to add header files to a Makefile.am), so it's always a good idea to double check that everything required will be distributed.
Don't forget to push master back to the public repo!
The tarball itself goes into voodoo:/home/httpd/research.wand.net.nz/html/software/libtrace/
Update voodoo:/home/httpd/research.wand.net.nz/html/software/libtrace.php to point at the correct file and include the new version number.
Use previous announcement posts as a template. Just mention major changes and bug fixes in the post itself; everything else is covered by linking to the ChangeLog.
Send an announcement to the [email protected] mailing list
Again, use previous announcement posts as a template.
All mail to this list has to be approved by a moderator. At the time of writing, Shane is a moderator.
git push origin --delete <rc branch name>