Release Process for Linaro binutils

As of the GNU Binutils 2.24 release, the binutils source code now resides in a git repository that is shared with GDB.

Linaro mirrors this new repository at the following location:

git://git.linaro.org/toolchain/binutils-gdb.git

This document describes the process of creating Linaro releases of stable GNU Binutils releases using this repository.

For each upstream GNU Binutils stable branch release Linaro will have a corresponding Linaro binutils branch that lives within the Linaro mirror.

Note: It is intended that eventually the Linaro branches of GNU Binutils will live in the upstream repository as well.

First Steps


Check to see if there is an up-to-date Linaro branch that tracks the latest stable release branch from upstream. This will determine whether a new Linaro branch of GNU Binutils needs to be created or if an existing Linaro branch should be updated for this release.

Note: For the purpose of this process document release version XX represents the current latest upstream stable release number, and version WW indicates the previous version.

  1. Start by cloning a fresh source tree and looking at the available binutils branches. You will be doing a git push, so you need permissions to push to the repository and will need to use the ssh:// protocol for your checkout (otherwise you have to specify the remote url directly during your push).

    git clone ssh://git.linaro.org/toolchain/binutils-gdb.git
    cd binutils-gdb.git
  2. Look at the upstream binutils branches that have been released:
    git branch -a | grep binutils
  3. Compare the latest binutils-2_YY-branch branch to the latest Linaro binutils branch:

    git branch -a | grep linaro | grep binutils
  4. If the latest Linaro binutils branch is linaro_binutils-2_WW-branch and the latest upstream stable branch is binutils-2_XX-branch then a new Linaro branch of GNU binutils needs to be created. Proceed to the section entitled Create a New Linaro Branch of GNU Binutils.

  5. Otherwise proceed to the section entitled Updating an Existing Linaro Branch of GNU Binutils.

Note: For critical performance and security fixes it might be necessary to update more than the current Linaro branch of GNU Binutils.

Creating a New Linaro Branch of GNU Binutils


  1. Create a new Linaro branch of GNU Binutils:
    git checkout -b local_linaro_binutils-2_XX-branch origin/binutils-2_XX-branch
  2. Add the required changes to src-release.sh for the Linaro branding (see previously used branch)
  3. Update the bfd/ChangeLog.linaro file to indicate that a new Linaro branch of GNU Binutils has been created (though not yet 'released').

    20XX-XX-XX  First Last  <[email protected]>
    
            Linaro binutils 2.XX branch created.
  4. Add the modified bfd/ChangeLog.linaro file.

    git add bfd/ChangeLog.linaro
  5. Commit the changes to the local branch.
    git commit
  6. Create a version relevant git commit message:
    Created Linaro branch of GNU Binutils 2.YY.
  7. Since the newly created branch already tracks the latests updates to the tracked branch the section on merging from the tracked branch can be skipped.
  8. Push the new branch to the Linaro binutils-gdb.git repository.

    git push origin local_linaro_binutils-2_YY-branch:linaro_binutils-2_YY-branch
  9. Proceed to the section entitled Cherry-picking Changes from the Upstream Master Branch.

Updating an Existing Linaro Branch of GNU Binutils


  1. Check out a local copy of the existing Linaro branch of GNU Binutils:
    git checkout -b local_linaro_binutils-2_XX-branch origin/linaro_binutils-2_XX-branch
  2. Proceed to the section entitled Merging Changes From the Tracked Branch.

Merging Changes from the Tracked Branch


Since the last time the Linaro branch was released the tracked upstream stable release branch might have had updates. These updates need to be merged into the linaro_binutils-2_XX-branch.

  1. Update the git remotes with the latest version of the upstream branch.
    git fetch origin
  2. Merge the tracked branch changes into the current branch. This will add a series of commits to your local_linaro_binutils-2_XX-branch.

    git merge origin/binutils-2_XX-branch
  3. These changes will be pushed to the linaro_binutils-2_XX-branch in a later step (once the release is tagged).

  4. If there is a conflict during the merge proceed to the section entitled Dealing With Merge Conflicts from the Tracked Branch.

  5. Otherwise Proceed to the section entitled Cherry-picking Changes from the Upstream Master Branch.

Dealing With Merge Conflicts from the Tracked Branch

In the event that an upstream feature was backported into the Linaro release branch before it was backported into the stable upstream release branch it might happen that the upstream release branch picks up change in the future. At this point, a Linaro release update (via a git merge) might create a conflict.

  1. Back out the erroneous merge
  2. Revert the patch that was applied to the Linaro branch by reverse applying the patch.
  3. Restart the merge (and hope the conflict goes away).


// TODO: Add git commands for above

Cherry-picking Changes from the Upstream Master Branch


After merging in the changes from the upstream release branch (if necessary) determine if the upstream stable release branch that the current Linaro branch release is tracking does not yet contain a feature that is desired for the current Linaro branch of Binutils. If so it will be necessary to cherry-pick that upstream feature from the master branch into the Linaro branch.

  1. Look at the commit log of the upstream master branch.
    git log origin/master
  2. Find the commit-id of the feature in the log, e.g. 1234567
  3. Attempt to cherry-pick the upstream feature into the existing branch. If successful this will automatically commit the fix to the local Linaro release branch.
    git cherry-pick [-x] 1234567
  4. If there is a failure then resolve the conflict and git commit -c.

  5. Update the directory relative ChangeLog.linaro files that correspond to the cherry-picked commit. For instance if the cherry-picked change modified files in the bfd/ directory copy the ChangeLog entry that the commit added to bfd/ChangeLog onto the top of bfd/ChangeLog.linaro. This is most easily done by using git show 1234567 and visually determining which ChangeLog files have been modified.

  6. Commit the changes to the ChangeLog.linaro files.

    git add -A
    git commit
  7. Proceed to the section entitled Updating the Linaro Branch Release Information.

Updating the Linaro Branch Release Information


The branch needs to have the version number updated.

  1. Add a ChangeLog entry to the start of bfd/ChangeLog.linaro:

    20XX-XX-XX  First Last  <[email protected]>
    
            Linaro binutils 2.XX.X-20XX.XX[-X] released.
    
            * version.h: Update VERSION.

    Note on release numbers: The main release for a given month's milestone is called 2.XX.X-20XX.XX (e.g. 2.23.2-2013.06). Subsequent respins (if necessary) carry an additional respin number, starting at 1 (e.g. 2.23.2-2013.06-1).

  2. Edit bfd/version.h:

    #define BFD_VERSION_STRING  @[email protected] "Linaro 20XX.XX-X " @[email protected]
  3. Check in the changes
    git commit -a
  4. Tag the release
    git tag -a linaro_binutils-2_XX_X-20XX_XX[-X]_release
  5. Push the tags to the Linaro binutils-gdb.git repository mirror.

    git push --tags

Create the tarballs


  1. Export the sources
    git archive --format=tar --prefix=binutils-export/ HEAD | (cd .. && tar xf - )
  2. Switch to the new source tree
    cd ../binutils-export
  3. Run the release script


    This will build all generated files and package the release tarball.

    ./src-release.sh -x binutils
  4. Save the tarfile:
    mv binutils-linaro-2.XX.X-20XX.XX-X.tar.xz ../

Bump the development version number


  1. Change directory back to the binutils repository
    cd ../binutils-gdb
  2. Edit bfd/version.h:

    #define BFD_VERSION_STRING  @[email protected] "Linaro 20XX.XX-Y-git " @[email protected]

    (where Y is the number of the next respin, or 1 if this was the main release).

  3. Add this to the start of bfd/ChangeLog.linaro:

    20XX-XX-XX  First Last  <[email protected]>
    
            * version.h: Bump version.
  4. Check in all of the changes
    git commit -a
    git push

Verify the release

  1. Build and test the release sources as thoroughly as possible.
    • Build binutils and run the testsuite natively on arm-linux-gnueabihf
    • Build binutils and run the testsuite in cross configuration for armeb-linux-gnueabihf
    • Build binutils and run the testsuite natively on aarch64-linux
    • Build binutils and run the testsuite in cross configuration for aarch64_be-linux
    • Build binutils with --enable-targets=all

Publishing the release

See WorkingGroups/ToolChain/PublishingARelease.

WorkingGroups/ToolChain/BinutilsReleaseProcess (last modified 2015-01-05 16:15:28)