Confluence has been migrated and upgraded. Please file an INFRA ticket if you see any issues.

Page tree
Skip to end of metadata
Go to start of metadata

Software Prerequisites


Traffic Control strives for quarterly releases. For example:

Q1 - release: 4.1, scope: X, RM: Y, start: jan 1, end: march 31
Q2 - release: 5.0, scope: X, RM: Y, start: april 1, end: june 30
Q3 - release: TBD, scope: X, RM: Y, start: july 1, end: sep 30
Q4 - release: TBD, scope: X, RM: Y, start: oct 1, end: dec 31 

On the start date: the designated RM should start the conversation (via the dev and users mailing list) about what the goals for the upcoming release will be. Based on this email conversation, the RM can optionally use issues and/or milestone to capture the scope for the release. At a minimum, most larger items should be identified. If the scope of the release is large, then a major release is probably proposed. If the release is smaller, then a minor release is probably proposed.

Two weeks prior to the end date: the designated RM announces the upcoming release in the public Slack traffic-control-cdn#dev channel as well as the dev and users mailing lists.

On the end date: the designated RM cuts the release branch from master (5.0.x for example) and builds the first release candidate (RC0) and starts the process of getting the release approved.

If this is your first release as a release manager, you must place your GPG Public Key into the KEYS file via SVN in

$ svn co -N

$ vi KEYS

$ svn status # to make sure the KEYS file shows as modified

$ svn commit -m "Update KEYS file for Release Manager"

Release Process Overview

The following steps assume a fictional release of 3.0.0 is already in production and the 3.1.0 release is about to become a formal release. The typical flow is to build a "Release Candidate (RC)" that can be voted on by the community, which means if there are bugs or enhancements that need to get into the RC then subsequent RC tags will ensue. Only fixes that correct problems are allowed through "Cherry Picks" for the RC: no enhancements.

Once the community all votes "+1" on the RC (a margin of at least 3 "+1" votes is required) , then a "Release" tag+build of the source tarball is created and gpg signed for public consumption.

Release Management Steps

Prepare Release Build and Branch

  1. In Jenkins, create a copy of the trafficcontrol-master-build specific to the new release branch.  All jobs can be found here:
    1. Go to
    2. Enter a new name for the job, e.g. trafficcontrol-3.1.x-build (if cutting the 3.1.0 release).
    3. Scroll to the bottom where it says "Copy from", enter "trafficcontrol-master-build", then click OK.
    4. Update the references to the "master" branch to "3.1.x" (e.g. if cutting the 3.1.0 release) in the job config, then save.
  2. Update the file on the master branch and commit+push.
    1. the current top-level "[unreleased]" section header should be changed to e.g. "## [3.1.0] - 2018-10-30"
    2. at the bottom, update the "[unreleased]" link to e.g. "[3.1.0]:". This link shows the diff between the new and prior versions.
  3. Update Traffic Router pom.xml files on the master branch to the new version, e.g. 3.1.0, and commit+push. For example, see this commit
  4. Verify that the top-level VERSION file on the master branch matches the version you want to release, e.g. 3.1.0. If it doesn't already match, then update it and commit+push.
  5. Run the misc/ script to cut the new release branch off master:
    1. $ cd trafficcontrol
    2. $ misc/ --gpg-key=<Release Manager Key ID> --release-no=RELEASE-3.1.0-RC1 cut

      NEW Release Prompt:
      NEW Release Summary
      Git Repo :
      Version : 131.0
      Branch : 3.1.x
      Tag : RELEASE-3.1.0-RC1
      Git Short Hash : 8eef5e5
      Next Version : 3.2.0
      Continue with creating the RELEASE? (Y/N): Y

      RELEASE CANDIDATE Release Prompt:
      Release CANDIDATE Summary
      Git Repo :
      Version : 3.1.0
      Branch : 3.1.x
      Next Tag : RELEASE-3.1.0-RC2
      Git Hash : 2876438
      Continue with creating the RELEASE? (Y/N): Y
    3. This script will automate the following high level steps:
      • Checkout the repo to /tmp/trafficcontrol
      • Create a new release branch, or use an existing branch for managing the release (ie: 3.1.x)
      • Tag the release with the release-no option given (ie: RELEASE-3.1.0-RC1)
      • Update the VERSION file according to the parameters given and commit it
      • Push the new release (or tag the existing) upstream to the public repo
  6. Once the tag is pushed, verify it.
    1. $git fetch --tags
    2. $git tag -v RELEASE-3.1.0-RC1
      object 66199be84c02ea62a952168ce8c9e68e0d2db79a
      type commit
      tag RELEASE-3.0.1-RC1
      tagger Derek Gelinas <derek@Kabletown.local> 1539188455 -0400

      Release 3.1.0
      gpg: Signature made Wed Oct 10 12:20:55 2018 EDT
      gpg:                using RSA key FE2B6AD8A1A214D9FF0AE5D6209FA95905BE71D9
      gpg: Good signature from "Derek Gelinas <>" [ultimate]
    3. If the key is trusted and has a good signature, then you can move on to creating the release candidate.  If the signature is not good, you need to ensure that your key is signed and trusted.  I had a trusted key, but recently reinstalled my OS which resulted in my key not showing as trusted.  To resolve this, I ran the following:
      $gpg --edit-key 05be71d9
      gpg (GnuPG/MacGPG2) 2.2.10; Copyright (C) 2018 Free Software Foundation, Inc.
      This is free software: you are free to change and redistribute it.
      There is NO WARRANTY, to the extent permitted by law.

      Secret key is available.

      sec  rsa4096/209FA95905BE71D9
           created: 2018-04-24  expires: 2022-04-24  usage: SC
           trust: full          validity: unknown
      ssb  rsa4096/767A5938418CB1
           created: 2018-04-24  expires: 2022-04-24  usage: E
      [ unknown] (1). Derek Gelinas <>

      gpg> trust
      sec  rsa4096/209FA95905BE71D9
           created: 2018-04-24  expires: 2022-04-24  usage: SC
           trust: full          validity: unknown
      ssb  rsa4096/767A5938418CB1
           created: 2018-04-24  expires: 2022-04-24  usage: E
      [ unknown] (1). Derek Gelinas <>

      Please decide how far you trust this user to correctly verify other users' keys
      (by looking at passports, checking fingerprints from different sources, etc.)

        1 = I don't know or won't say
        2 = I do NOT trust
        3 = I trust marginally
        4 = I trust fully
        5 = I trust ultimately
        m = back to the main menu

      Your decision? 5
      Do you really want to set this key to ultimate trust? (y/N) y

      sec  rsa4096/209FA95905BE71D9
           created: 2018-04-24  expires: 2022-04-24  usage: SC
           trust: ultimate      validity: unknown
      ssb  rsa4096/767A5938418CB1
           created: 2018-04-24  expires: 2022-04-24  usage: E
      [ unknown] (1). Derek Gelinas <>
      Please note that the shown key validity is not necessarily correct
      unless you restart the program.

      gpg> quit
    4. Delete the tag created in the beginning of step 4 using
      $git push --delete origin RELEASE-3.1.0-RC1
    5. Recreate the key as in step 4b and verify that it is trusted.

Create Release Candidate

Follow these steps by substituting your version information with the 3.1.x or 3.1.0 steps below to build a release candidate. 

  • Verify Weasel results
  • Download and Sign Tarball
  • Send Vote Email

Verify Weasel Results

  1. Run the release build created above (e.g. trafficcontrol-3.1.x-build). Once it's complete, look for weasel.txt in the artifacts directory of the build.  The file should be empty - if it is not, then address any errors found.

Download and Sign Release Tarball

  1. Download the tarball from the artifacts directory of the build.
  2. Generate GPG and SHA512 signatures
    $ gpg --armor --detach-sig apache-trafficcontrol-<VERSION>.tar.gz
    $ shasum -a512 apache-trafficcontrol-<VERSION>.tar.gz > apache-trafficcontrol-<VERSION>.tar.gz.sha512

  3. Post Release candidate to dist/dev location. Once the vote passes, the tarball should be renamed and uploaded to the dist/release location. Nothing else other than the filename may change- the release signatures must match the voted on signatures exactly. 

    $ svn co -N (or for golden release images only:

    $ mkdir -p trafficcontrol/3.1.0/RC1

    $ mv apache-trafficcontrol-<VERSION>.tar.gz.* trafficcontrol/3.1.0/RC1 # Should be 3 files: tgz, sha512, asc

    $ svn add  3.1.0 (or svn add RC1 if 3.1.0 is already added)

    $ svn status   # Confirm files are added to working area

    $ svn commit --username <ASF username> -m "apache-trafficcontrol-3.1.0-RC1"

Send Vote Email

The PMC must vote and approve on a release candidate.  The PMC list can be found at  Three binding (PMC Member) votes are needed for release.  Non-PMC votes do not count toward the three vote requirement.

PMC Vote To: (Do NOT send to users@)

Subject: [VOTE] Release Apache Traffic Control <version>-RC<version>


Hello All,

I've prepared a release for v<version>-RC<version>

The vote is open for at least 72 hours and passes if a majority of at least 3 +1 PMC votes are cast.

[ ] +1 Approve the release

[ ] -1 Do not release this package because ...

Changes since <previous_released_version>:<previous_released_version>...RELEASE-<version>-RC<version>

This corresponds to git:
Hash: <commit_hash>
Tag: RELEASE-<version>-RC<version>

Which can be verified with the following: git tag -v RELEASE-<version>-RC<version>

My code signing key is available here:<insert your GPG key ID here>&op=vindex

Make sure you refresh from a key server to get all relevant signatures.

The source .tgz file, pgp signature (.asc signed with my key from
above), and sha512 checksums are provided here:<version>/RC<version>

<your_name> <your_email_address>

To get the vote result

  1. Browse to
  2. Click on the vote email
  3. Click the yellow "permalink" button
  4. Copy the URL from the URL bar

Send Vote Result Email


Subject: [RESULT][VOTE] Release Apache Traffic Control <version>-RC<version>


Thanks to all who voted!

The release has PASSED with the following PMC votes:

+1 <voter's name> (binding)
+1 <voter's name> (binding)
+1 <voter's name> (binding)

I will proceed to publish the release and send ANNOUNCE.

On behalf of Apache Traffic Control, thank you!

<your_name> <your_email_address>

Finalizing a Release

  1. Confirm there are no show-stoppers in the Traffic Control issues here:

  2. Create or Update release notes (GitHub) using the version notes in

  3. Create a new release on Github using the script.  This should not be done until the above changes have been made.

  4. Update the release repository at via SVN. You will want to remove the earliest release as only two releases should be listed here. These will automatically be mirrored, so your actual download links on the website will point to<release>/<file>

    $ svn co
    $ cd trafficcontrol
    $ mkdir 3.1.0
    $ # copy the final .tar.gz, .tar.gz.asc, and .tar.gz.sha512 release candidate artifacts into 3.1.0/

    $ svn add 3.1.0
    $ svn delete 3.0.2
    $ svn status
    $ svn commit -m "apache-trafficcontrol-3.1.0"

  5. Update the news, releases, and default profiles on via the repo, asf-site branch.

  6. Update Documentation Version Numbers and activate the readthedocs build. Login to Contact one of the PMC members to add your user. Click `Versions` from the top menu. Find your version in the list of inactive versions. Click `Edit`, and activate the version. The version should be built and made available in a few minutes.

  7. Send announce email, detailed below.

Announce Email


Subject: [ANNOUNCE] Release Apache Traffic Control <version>


The Apache Traffic Control team is proud to announce the release of Apache Traffic Control <version>.

More details regarding Apache Traffic Control can be found at:

The release artifacts, along with release notes, can be found here:


The Apache Traffic Control Team

  • No labels