Skip to content

Latest commit

 

History

History
346 lines (250 loc) · 12.9 KB

RELEASING.md

File metadata and controls

346 lines (250 loc) · 12.9 KB

Contents

BLIS version numbering scheme and branching strategy

BLIS uses a major.minor version numbering scheme. An increase in the major version number (a "major release" or simple "new version") indicates new (usually significant) functionality, and possible incompatibility with previous major releases, although the ABI version can be used to check for compatibility across major version in principle.

Major releases have one or more "release candidates" which are preliminary versions of the next release, publicly distributed for comment and/or bug discovery. Subsequent release candidates (rcs) correct problems found in the previous rc. Once a reasonable level of stability is achieved, the full release is distributed.

An increase in the minor version number (a "point release") indicates the incorportation of one or more bugfixes or other minor changes since the initial major version release or last point release.

Essentially, point releases extend the rc cadence beyond the official release by correcting additional problems discovered after release.

All rcs, initial major release, and point releases are created along a linear git branch, named for the major release lineage, e.g. r1.x. Commits indicating rcs and releases are tagged (e.g. 1.0-rc0, 1.0, 1.1) and also have an associated non-tip branch (e.g. r1.0-rc0, r1.0, r1.1). Using both tags and branches increases visibility of important commits, but new commits should only be made on the r1.x lineage branch.

Release lineage branches diverge from master starting with the first rc. Any new commits on the release lineage (except version maintenance commits such as updating the version file, CHANGELOG, and release notes) are cherry-picked from master. Exceptions may be made if, for example, a backported bugfix cannot be cherry-picked and requires a more targeted fix directly on a release branch.

Here is an example illustration of the release branch structure:

_________________________________________________________master
   \                    \
    \                    \__r2.0-rc0_____r2.0-rc1_____r2.0,r2.x
     \                      (2.0-rc0)    (2.0-rc1)    (2.0)
      \
       \__r1.0-rc0_____r1.0-rc1_____r1.0_____r1.1_____r1.2,r1.x
          (1.0-rc0)    (1.0-rc1)    (1.0)    (1.1)    (1.2)
                                     /\
      <- release candidates -- major release -- point releases ->

In each case, the version number (as encoded in the version file) indicates the x.y prefix of the most recent tagged commit. The exception is master, where the version file indicates z.0-dev, where z is the major version number one higher than the latest major release (e.g. 3.0-dev in the example above).

Instructions for creating a new release candidate or point release of BLIS

Creating a new release lineage branch

  1. Consider whether the so_version should be updated (via the build/so_version file) due to any ABI changes since the previous version. If so, commit that change on master now.

  2. Create the new release lineage branch.

    $ git checkout master
$ git pull
$ git branch r2.x

    Note that the new release lineage branch should not be check out at this point.

  3. Update the version on the master branch to reflect the next release in development.

    $ ./build/do-release.sh -b "3.0-dev"
$ git push

    Note the extra option -b.

  4. Check out the new release lineage branch.

    $ git checkout r2.x

Creating a new release candidate (e.g. 1.x -> 2.0-rc0 or 2.0-rc0 -> 2.0-rc1)

  1. Make sure that the release lineage branch is checked out and up-to-date.

    $ git checkout r2.x
$ git pull

  2. Draft a new announcement to the blis-devel mailing list, crediting those who contributed towards this version by browsing git log.

  3. Update the CREDITS file if git log reveals any new contributors. NOTE: This should have already been done prior to the rc cycle.

  4. Commit the updated CREDITS file if changed.

  5. Update docs/ReleaseNotes.md with the body of finalized announcement and the date of the release. Developers are encouraged to update the release notes on master as new changes are made, which simplifies preparation of rc0.

  6. Commit the updated docs/ReleaseNotes.md file.

  7. Use the build/do-release.sh script to create a new rc branch and tag.

    $ ./build/do-release.sh "2.0-rc<n>"

    Where <n> is 0 for the first rc, or one higher than the last rc on this release lineage branch.

  8. Make sure the do-release script and other commits did what they were supposed to do by inspecting the output of git log. If everything looks good, you can push the changes via:

    $ git push
$ git push --tags
$ git push -u <origin> 2.0-rc<n>

    Where <origin> is the name of the appropiate upstream git remote.

    At this point, the new release candidate branch is live at <origin>.

  9. Announce the rc release on blis-devel, Discord, and/or other appropriate venues.

  10. Wait for bug reports. Typically an rc should stay live for at least a month in order to give users time to try it out.

  11. After the trial period, cherry-pick any bugfixes or other updates:

    $ git cherry-pick [-nx]

    Be sure to include lines in the commit log entry for each cherry-picked commit that note the commit hash of the original commit that is being cherry-picked from. Example:

    Fixed a bug in blahblahblah. (#777)

Details:
 - Fixed a bug in blahblahblah that manifested as blahblahblah. This
   bug was introduced in commit abc12345. Thanks to John Smith for
   reporting this bug.
 - (cherry picked from commit abc0123456789abc0123456789abc0123456789a)

    Note the final line, which was not present in the original commit log entry (on master) but should be present in the commit log entry for the cherry-picked commit (on the release lineage branch).

  12. If no bugs are reported/found, or if the updated rc is otherwise ready for promotion to full release, continue with the instructions below. Otherwise, return to step 2, incrementing <n>.

Creating a new major release (e.g. 2.0-rc<n> -> 2.0)

  1. Make sure that the release lineage branch is checked out and up-to-date.

    $ git checkout r2.x
$ git pull

  2. Draft a new announcement to the blis-devel mailing list, crediting those who contributed towards this version by browsing git log.

  3. Update the CREDITS file if git log reveals any new contributors. NOTE: This should have already been done prior to the release cycle.

  4. Commit the updated CREDITS file if changed.

  5. Update docs/ReleaseNotes.md with the body of finalized announcement and the date of the release. Developers are encouraged to update the release notes on master as new changes are made, which simplifies preparation of the release.

  6. Commit the updated docs/ReleaseNotes.md file.

  7. Use the build/do-release.sh script to create a new release branch and tag.

    $ ./build/do-release.sh "2.0"

  8. Make sure the do-release script and other commits did what they were supposed to do by inspecting the output of git log. If everything looks good, you can push the changes via:

    $ git push
$ git push --tags
$ git push -u <origin> 2.0

    Where <origin> is the name of the appropiate upstream git remote.

    At this point, the new release branch is live at <origin>.

  9. Publish a new release via GitHub (https://github.com/flame/blis/releases). Identify the new version by the tag you just created and pushed. You can also identify the previous release.

    Try to use formatting consistent with the prior release. (You can start to edit the previous release, inspect/copy some of the markdown syntax, and then abort the edit.)

  10. Announce the rc release on blis-devel, Discord, and/or other appropriate venues.

  11. Update the Wikipedia entry for BLIS to reflect the new latest version.

Back-porting fixes from master to releases

  1. When a bug fix is developed on master which is applicable to a supported release, and corrects a significant problem with correctness, usability, or performance (e.g. not new functionality or cosmetic changes), it should be back-ported. Bug fixes should be individually back-ported to all supported releases.

  2. Check out the relevant release lineage branch, e.g.:

    $ git checkout r2.x
$ git pull

  3. Verify that the bug affects this release lineage. If not, skip this release lineage.

  4. If possible, cherry-pick the bugfix commit from master:

    $ git cherry-pick [-nx]

    Be sure to include lines in the commit log entry for each cherry-picked commit that note the commit hash of the original commit that is being cherry-picked from. Example:

      Fixed a bug in blahblahblah. (#777)

  Details:
  - Fixed a bug in blahblahblah that manifested as blahblahblah. This
    bug was introduced in commit abc12345. Thanks to John Smith for
    reporting this bug.
  - (cherry picked from commit abc0123456789abc0123456789abc0123456789a)

    Note the final line, which was not present in the original commit log entry (on master) but should be present in the commit log entry for the cherry-picked commit (on the release lineage branch).

  5. If cherry-picking is not possible (e.g. the commit does not merge cleanly, underlying implementation details or internal APIs have changed, etc., then craft a new bugfix on the release lineage branch. Make sure to test the new bugfix against the reported bug, as well as the full BLIS testsuite!

  6. Push the changes via git push. Do not update any other release branches or tags at this time.

Creating a new point release (e.g. 1.1 -> 1.2 or 2.0 -> 2.1)

  1. Once enough bug fixes have accumulated, a bug fix of high enough urgency, or a pre-determined period of time has elapsed, all bug fix commits since the last release (major or point release) will be included in a new point release.

    Point releases can be made on either the most recent release lineage branch or on a "historical" but still supported release lineage.

  2. Check out the relevant release lineage branch (which may not be the most recent)

    $ git checkout r2.x
$ git pull

  3. Draft a new announcement to the blis-devel mailing list, crediting those who contributed towards this version by browsing git log.

  4. Update the CREDITS file if git log reveals any new contributors. NOTE: This should have already been done prior to the release cycle.

  5. Commit the updated CREDITS file if changed.

  6. Update docs/ReleaseNotes.md with the body of finalized announcement and the date of the release.

  7. Commit the updated docs/ReleaseNotes.md file.

  8. Use the build/do-release.sh script to create a new release branch and tag.

    $ ./build/do-release.sh "2.1"

  9. Make sure the do-release script and other commits did what they were supposed to do by inspecting the output of git log. If everything looks good, you can push the changes via:

    $ git push
$ git push --tags
$ git push -u <origin> 2.1

    Where <origin> is the name of the appropiate upstream git remote.

    At this point, the new release branch is live at <origin>.

  10. Update the release target branch via GitHub (https://github.com/flame/blis/releases). Identify the new version by the tag you just created and pushed. You can also identify the previous release.

    Try to use formatting consistent with the prior release. (You can start to edit the previous release, inspect/copy some of the markdown syntax, and then abort the edit.)

  11. Announce the rc release on blis-devel, Discord, and/or other appropriate venues.

  12. If this point release is for the most recent major release lineage, update the Wikipedia entry for BLIS to reflect the new latest version.