diff --git a/RELEASING b/RELEASING deleted file mode 100644 index 85de229c99..0000000000 --- a/RELEASING +++ /dev/null @@ -1,135 +0,0 @@ -Here are the steps to follow to create a new release candidate of BLIS: - -If you're creating a new release candidate lineage -- that is, the *first* -release candidate for a new version (i.e., 2.0-rc0): - -1. Use the build/start-new-rc.sh script to create a new rc branch. - - $ ./build/start-new-rc.sh "2.0" - - This will update the version file in BLIS to reflect the new version - string (in this case, "2.0"). It also refreshes the contents of the - CHANGELOG file with the output of 'git log'. Finally, it creates a - new "-rc0" branch (in this case, "2.0-rc0"). - - NOTE: This script assumes that you want the new rc branch to be - a descendant of the head of 'master'. - -2. Make sure the script did what it was supposed to do by inspecting - the output of 'git log' and 'git branch'. If everything looks good, - you can push the changes via: - - $ git checkout master - $ git push - $ git push -u origin 2.0-rc0 - - At this point, the new release candidate branch is live at origin. - -If you're creating a new release candidate for an existing lineage --- that is, a follow-up release candidate for a new version that already -has one or more release candidates -- start by checking out the latest -release candidate, for example: - -1. Start by checking out the latest release candidate: - - $ git checkout 2.0-rc1 - -2. Then create a new release candidate branch whose name increments the - "rc" number: - - $ git checkout -b 2.0-rc2 - -3. Then cherry-pick one or more bugfixes that were made to 'master': - - $ git cherry-pick -nx - -4. Finally, commit the changes. 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 but *should be* present in the commit log entry for the - commit that cherry-picks to (in this example) 2.0-rc2. - - -Here are the steps to follow to create a new release (version) of BLIS: - -1. Make sure there are no commits that have yet to be pulled into - local repository. - - $ git pull - - If there are any commits upstream, merge them as appropriate. - -2. Check out the latest release candidate: - - $ git checkout 2.0-rc2 - -3. Consider whether the so_version should be updated (via the so_version - file in the 'build' directory) due to any ABI changes since the previous - version. If so, commit that change now. - -4. Verify that the code builds properly. - - $ ./configure auto; make - -5. Verify that the code passes BLIS and BLAS tests: - - $ make check # BLIS testsuite (fast) + BLAS test drivers - $ make checkblis # BLIS testsuite (full ex. mixed-datatype) - $ make checkblis-md # BLIS testsuite (mixed-datatype only) - $ make checkblis-salt # BLIS testsuite (fast + salt) - -6. Draft a new announcement to blis-devel, crediting those who - contributed towards this version by browsing 'git log'. - -7. Update CREDITS file if 'git log' reveals any new contributors. - NOTE: This should have already been done prior to the rc cycle. - -8. Update docs/ReleaseNotes.md file with body of finalized announcement - and the date of the release. - NOTE: This should be a cherry-pick off of 'master' since the release notes - need to be committed there anyway as well. - -9. Commit changes from steps 7 and 8. - -10. Create a final release branch: - - $ git checkout -b 2.0-final - - This will help identify the release commit when browsing the GitHub network - graph, since tags don't show up there. - -11. Tag the final release commit: - - $ git tag 2.0 2.0-final - - You can also use the actual commit hash instead of "2.0-final". - -12. Push the new commits and new tag associated with the new version: - - $ git push - $ git push --tag - -13. 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.) - -14. Update the Wikipedia entry for BLIS to reflect the new latest version. - -15. Announce the release on Discord. - -16. Send finalized announcement to blis-devel. - diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000000..9496b396a4 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,346 @@ +## Contents + +* **[BLIS version numbering scheme and branching strategy](RELEASING.md#blis-version-numbering-scheme-and-branching-strategy)** +* **[Instructions for creating a new release candidate or point release of BLIS +](RELEASING.md#instructions-for-creating-a-new-release-candidate-or-point-release-of-blis +)** + * **[Creating a new release lineage branch +](RELEASING.md#creating-a-new-release-lineage-branch)** + * **[Creating a new release candidate (e.g. `1.x` -> `2.0-rc0` or `2.0-rc0` -> `2.0-rc1`)](RELEASING.md#creating-a-new-release-candidate-eg-1x---20-rc0-or-20-rc0---20-rc1)** + * **[Creating a new major release (e.g. `2.0-rc` -> `2.0`)](RELEASING.md#creating-a-new-major-release-eg-20-rcn---20)** + * **[Back-porting fixes from `master` to releases](RELEASING.md#back-porting-fixes-from-master-to-releases)** + * **[Creating a new point release (e.g. `1.1` -> `1.2` or `2.0` -> `2.1`)](RELEASING.md#creating-a-new-point-release-eg-11---12-or-20---21)** + +## 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" + ``` + + Where `` 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 2.0-rc + ``` + + Where `` is the name of the appropiate upstream git remote. + + At this point, the new release candidate branch is live at ``. + +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 ``. + +### Creating a new major release (e.g. `2.0-rc` -> `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 2.0 + ``` + + Where `` is the name of the appropiate upstream git remote. + + At this point, the new release branch is live at ``. + +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! + +7. 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 2.1 + ``` + + Where `` is the name of the appropiate upstream git remote. + + At this point, the new release branch is live at ``. + +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. diff --git a/build/start-new-rc.sh b/build/do-release.sh similarity index 66% rename from build/start-new-rc.sh rename to build/do-release.sh index 786522214a..97c906695f 100755 --- a/build/start-new-rc.sh +++ b/build/do-release.sh @@ -1,6 +1,6 @@ #!/bin/sh # -# BLIS +# BLIS # An object-based framework for developing high-performance BLAS-like # libraries. # @@ -41,46 +41,45 @@ print_usage() { - #local script_name - - # Get the script name - #script_name=${0##*/} - - # Echo usage info - echo " " - echo " "$script_name - echo " " - echo " Field G. Van Zee" - echo " " - echo " Performs a series of actions needed when creating a new release" - echo " candidate branch for BLIS:" - echo " 1. Overwrite the version file with the version string passed" - echo " into this script ()." - echo " 2. Commit the updated version file." - echo " 3. Update the CHANGELOG file." - echo " 4. Commit the updated CHANGELOG file." - echo " 5. Create a new branch (named '-rc0') which refers to" - echo " the commit created in (4)." - echo " " - echo " Usage:" - echo " ${script_name} [options] new_vers" - echo " " - echo " Arguments:" - echo " " - echo " new_vers The new version string." - echo " " - echo " Options:" - echo " " - echo " -d dry-run" - echo " Go through all the motions, but don't actually make any" - echo " changes to files or perform any git commits. Note that" - echo " this will result in the commits for (2) and (5) above" - echo " being equal to the initial commit in the script output." - echo " -f VERSFILE version file name" - echo " Update VERSFILE with new version string instead of default" - echo " 'version' file." - - # Exit with non-zero exit status + echo <<- EOF + + $script_name + + Field G. Van Zee + + Performs a series of actions needed when creating a new release + candidate branch for BLIS: + 1. Overwrite the version file with the version string passed + into this script (). + 2. Commit the updated version file. + 3. Update the CHANGELOG file. + 4. Commit the updated CHANGELOG file. + 5. Create a new branch (named 'r') which refers to + the commit created in (4). + 6. Tag the commit created in (4) with a tage ''. + + Usage: + ${script_name} [options] new_vers" + + Arguments: + + new_vers The new version string. + + Options: + + -b bare update + Update the version and CHANGELOG files but do not create + a release branch or tag. + -d dry-run + Go through all the motions, but don't actually make any + changes to files or perform any git commits. Note that + this will result in the commits for (2) and (4) above + being equal to the initial commit in the script output. + -f VERSFILE version file name + Update VERSFILE with new version string instead of default + 'version' file. + EOF + exit 1 } @@ -117,17 +116,21 @@ main() # The git directory. gitdir='.git' - + # Whether we are performing a dry run or not. - dry_run_flag="" + dry_run_flag="" + + # Whether we are doing a bare update or not. + bare_flag="" # -- END GLOBAL VARIABLE DECLARATIONS -- # Process our command line options. - while getopts ":dhf:" opt; do + while getopts ":dhbf:" opt; do case $opt in d ) dry_run_flag="1" ;; + b ) bare_flag="1" ;; f ) version_file=$OPTARG ;; h ) print_usage ;; \? ) print_usage @@ -152,10 +155,12 @@ main() if [ $# = "1" ]; then new_version_str=$1 - new_rc_str="${new_version_str}-rc0" + new_rc_str="r${new_version_str}" echo "${script_name}: new version string: '${new_version_str}'." - echo "${script_name}: preparing to create release candidate branch '${new_rc_str}'." + if [ -z "${bare_flag}" ]; then + echo "${script_name}: preparing to create release (candidate) branch '${new_rc_str}'." + fi else print_usage @@ -175,10 +180,8 @@ main() echo "${new_version_str}" > ${version_file} fi - echo "${script_name}: executing: git checkout ${master_br}." echo "${script_name}: executing: git commit -m \"Version file update (${new_version_str})\" ${version_file}." if [ -z "$dry_run_flag" ]; then - git checkout ${master_br} git commit -m "Version file update (${new_version_str})" ${version_file} fi @@ -187,13 +190,7 @@ main() echo "${script_name}: updating '${changelog_file}'." if [ -z "$dry_run_flag" ]; then - - # If 'make distclean' was run recently, we need to re-run - # configure in order for 'make changelog' to work properly. - if [ ! -f "${configmk_file}" ]; then - ./configure auto - fi - make changelog + git log --no-decorate > ${changelog_file} fi echo "${script_name}: executing: git commit -m \"CHANGELOG update (${new_version_str})\" ${changelog_file}." @@ -204,20 +201,28 @@ main() git_commit_str=$(git describe --always) echo "${script_name}: new commit containing CHANGELOG update: ${git_commit_str}." - echo "${script_name}: executing: git checkout -b ${new_rc_str}." - if [ -z "$dry_run_flag" ]; then - git checkout -b "${new_rc_str}" - fi + if [ -z "${bare_flag}" ]; then - echo "${script_name}: " - echo "${script_name}: FINAL STEPS: Check the output of 'git log'. If everything" - echo "${script_name}: looks okay, execute these commands manually:" - echo "${script_name}: " - echo "${script_name}: git checkout master" - echo "${script_name}: git push" - echo "${script_name}: git push -u origin ${new_rc_str}" - echo "${script_name}: " - + echo "${script_name}: Creating branch ${new_rc_str}." + if [ -z "$dry_run_flag" ]; then + git branch "${new_rc_str}" + fi + + echo "${script_name}: Tagging branch ${new_rc_str} with tag ${new_version_str}." + if [ -z "$dry_run_flag" ]; then + git tag "${new_version_str}" "${new_rc_str}" + fi + + echo "${script_name}: " + echo "${script_name}: FINAL STEPS: Check the output of 'git log'. If everything" + echo "${script_name}: looks okay, push the new branch manually:" + echo "${script_name}: " + echo "${script_name}: git push" + echo "${script_name}: git push --tags" + echo "${script_name}: git push -u origin ${new_rc_str}" + echo "${script_name}: " + + fi else