|
| 1 | +## UMF Release Steps |
| 2 | + |
| 3 | +This document contains all the steps required to make a new release of UMF. |
| 4 | + |
| 5 | +As a helper, we use in this guide these 2 variables: |
| 6 | +```bash |
| 7 | + set $VERSION = current full version (e.g., 0.1.0-rc1) # -rc1 included just as an example |
| 8 | + set $VER = current major+minor only version (e.g., 0.1) |
| 9 | +``` |
| 10 | + |
| 11 | +## Make a release locally |
| 12 | + |
| 13 | +Before doing the final release it's recommended to prepare a pre-release version - a "release candidate" |
| 14 | +(or "rc" in short). This requires adding, e.g., `-rc1` to the VERSION string. When all tests and checks |
| 15 | +end properly, you can follow up with the final release. If any fix is required, it should be included in |
| 16 | +another rc package (e.g., `-rc2`). |
| 17 | + |
| 18 | +To do a release: |
| 19 | +- Add an entry to ChangeLog, remember to change the day of the week in the release date |
| 20 | + - For major releases mention API and ABI compatibility with the previous release |
| 21 | +- Update project's version in top-level CMakeLists.txt |
| 22 | +- Commit these changes and tag the release: |
| 23 | + - git commit -a -S -m "$VERSION release" |
| 24 | + - git tag -a -s -m "Version $VERSION" $VERSION |
| 25 | + |
| 26 | +- Now, update project's version in top-level CMakeLists.txt to "$VERSION-devel" |
| 27 | + - This implies that the version is ahead of the previous tag and it's a development build |
| 28 | + - This way only one commit (the tagged one) will introduce itself as "$VERSION" in CMake |
| 29 | +- For major/minor releases add a new, empty ChangeLog entry (for $VERSION+1) |
| 30 | +- Commit these changes: |
| 31 | + - git commit -a -m "Update version to devel" |
| 32 | + |
| 33 | +- For major/minor release: |
| 34 | + - If stable branch for this release is not created and it's required, create it: |
| 35 | + - git checkout -b v$VER.x (e.g., `v0.1.x`) |
| 36 | + |
| 37 | +## Publish changes |
| 38 | + |
| 39 | +As patch releases should be done on the stable branches, pushing tags differ a little. |
| 40 | + |
| 41 | +For major/minor release: |
| 42 | + - Push main: |
| 43 | + - git push upstream HEAD:main $VERSION |
| 44 | + - And, if stable branch was also created, push it to upstream: |
| 45 | + - git checkout v$VER.x |
| 46 | + - git push upstream HEAD:v$VER.x |
| 47 | +- for patch release: |
| 48 | + - git push upstream HEAD:v$VER.x $VERSION |
| 49 | + |
| 50 | +## Announce release |
| 51 | + |
| 52 | +To make the release official: |
| 53 | +- go to [GitHub's releases tab](https://github.com/oneapi-src/unified-memory-framework/releases/new): |
| 54 | + - tag version: $VERSION, release title: UMF $VERSION, description: copy entry from ChangeLog and format it with no tabs and no characters limit in line |
| 55 | +- announce the release, if needed |
| 56 | + |
| 57 | +## More information |
| 58 | + |
| 59 | +To assure the community that the release is a valid package from UMF maintainers, it's recommended to sign the release |
| 60 | +commit and the tag (`-S`/`-s` parameters in commands above). If you require to generate a GPG key follow |
| 61 | +[these steps](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key). |
| 62 | +After that you'd also have to add this new key to your GitHub account - please do the steps in |
| 63 | +[this guide](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key). |
0 commit comments