-
Notifications
You must be signed in to change notification settings - Fork 192
Releases
This document gives information on releases and how to create them.
Releases in hypre are assigned a number of the form MAJOR.MINOR.PATCH, where an increment in one of the digits denotes the following (in general):
- MAJOR - backward incompatible release (API changes)
- MINOR - new features
- PATCH - bug fixes or other trivial changes
This approach is based loosely on Semantic Versioning, but ultimately the decision about any particular release name is subjective and made on an individual basis by the hypre team. Some additional discussion on versioning can also be found in roundup [issue1347].
Creating a release roughly involves the following: informing the other developers; bumping the release number; testing and finalizing the code; and tagging. First, create a GitHub issue titled "New hypre release {number}" to advise @Developers of the target release date and ask that master branch updates be avoided until it is complete. Also add the "releases" label to the issue. The following checklist (shown in raw markdown format) contains a detailed list of the remaining steps involved (using release number 2.11.0 as an example). Copy-and-paste it into the new GitHub release issue to be updated along the way (first change the example release number to the correct one).
- [ ] Create a PR with title "Release 2.11.0" on branch `release-2.11.0`.
- [ ] Create branch
- [ ] Update `CHANGELOG` file with information regarding contents of this release.
- [ ] Update `config/version.sh` with release number and date, then run `config/update.sh` and commit changes.
- [ ] Create PR, reference this issue in the description, and add reviewers
- [ ] [MAJOR] Documentation review(s).
- [ ] [MAJOR.MINOR] Update user and reference manuals.
- [ ] Check regression tests.
- [ ] machine-tux
- [ ] machine-tux-spack
- [ ] machine-mac
- [ ] machine-rztopaz
- [ ] machine-lassen
- [ ] machine-tioga
- [ ] machine-aurora
- [ ] Squash merge the PR.
- [ ] Tag repository with release number: `git tag -a v2.11.0 -m "Release v2.11.0"`
- [ ] Push tags to central repository: `git push --tags`
- [ ] Create a GitHub Release.
- [ ] On the CASC cluster, copy the GitHub release tar file to `/usr/casc/hypre`.
- [ ] On the RZ, copy the GitHub tar file to `/usr/gapps/hypre` (for backup reasons).
- [ ] Update Spack Package and create Spack pull request.
- [ ] Close the new release GitHub issue.
Releases are deployable software iterations that can be packaged and published for users to download. They allow customized notifications to users after deployment and an easy way to compare changes between different hypre versions through GitHub's web interface. Here are the basic steps for generating a GitHub release of hypre:
- Access https://github.com/hypre-space/hypre/releases
- Click on "Draft a new release" (top right)
- Select the latest version in
Choose a tag - Insert a release title such as "Release v2.11.0"
- Click on "Generate release notes" (top right of the "Describe this release" box)
- In the box "Describe this release", remove all text except the "Full Changelog" at the end.
- Click on "Update Release"
The hypre Spack package is located here. Once the release has been tagged, the Spack checksum command can be used to generate the new version information. This command fetches the available tarballs that were requested for a package and prints out a list of version commands ready to copy/paste into the package file. For a new version x.y.z, run the command:
spack checksum hypre x.y.z
The output is the version command that should be added to the list of available versions in the hypre Spack package, after the develop version. The recommended workflow is to use the GitHub Web Interface. From the hypre Spack package, click on "Edit this file" button (right of "Blame" button) to add the new version, update the commit information at the bottom of the page, then click "Propose changes" to create a new branch from you fork, then "Create pull request" to merge into Spack's develop branch.
Optionally if there are any changes to the configure options in the release like new options that should be included within the Spack build or any deprecations of configure options, this is a good time to update the hypre Spack package in a separate PR from the version addition update (as there should be more testing done with changes to the Spack build).
Test releases can sometimes be useful prior to official releases. Creating one basically involves tagging the repository with a special name that is generated via the git command git describe --tags {SHA-1 reference} where the "{SHA-1 reference}" is some specific git node (in short or long form) that can also be left blank (indicating the current node). The node can be on any branch in the repository. The name generated will look something like v2.15.1-69-g562c29a which refers to node 562c29a (short name) and indicates that it is 69 commits after the previous annotated tag v2.15.1 (standard releases are marked with annotated tags via the '-a' option above). This name can then be used to tag the node and create a test release as follows:
git tag 562c29a -m "Release v2.15.1-69-g562c29a"
git push --tags