Skip to content

Release Process

Jump to bottom
Shane Alcock edited this page Nov 14, 2017 · 6 revisions

This page documents the process that is currently used to prepare a new libtrace release.

Create a RC branch

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>

Update the ChangeLog on this wiki

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.

Update AUTHORS (if required)

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.

Increment version number

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.

Commit and push the above changes in the rc branch to the GitHub repo

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.

Test the rc branch code builds on various OS's

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.
  • 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 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.
  • Don't delete your VM until you've testing all candidate systems -- it is possible you might make a change on one system that you want to double check on another.
Clone this wiki locally