Merge pull request #1453 from lukaszstolarczuk/rel-steps

Update Release Steps

Author: lukaszstolarczuk

RELEASE_STEPS.md

@@ -4,8 +4,8 @@ This document contains all the steps required to make a new release of UMF.
 
 As a helper, we use in this guide these 2 variables:
 ```bash
-  set $VERSION = new full version (e.g., 0.1.0-rc1) # -rc1 included just as an example
-  set $VER = new major+minor only version (e.g., 0.1)
+  $VERSION=1.1.0-rc1  # New full version, including optional rc suffix as an example
+  $VER=1.1            # New major+minor only version
 ```
 
 **Note:**
@@ -19,47 +19,63 @@ will be released for a oneAPI release. Once all changes planned for UMF release
 we follow the process (described in more detail below):
 
 1. Checkout the appropriate branch (`main` or "stable" `v$VER.x`).
-2. Make changes for the release.
-3. Create a new tag based on the latest commit - it takes the form
+1. Make sure remotes are up-to-date on your machine (`git remote update`).
+1. Make changes for the release.
+1. Create a new tag based on the latest commit - it should follow the format:
   `v<major>.<minor>.<patch>` (e.g., `v0.1.0`).
-4. Push the tag and branch to the upstream.
-5. Create a new GitHub release using the tag created in the previous step.
-6. Update downstream projects to utilize the release tag. If any issues arise
+1. Push the tag and branch to the upstream.
+1. Create a new GitHub release using the tag created in the previous step.
+1. Update dependent/downstream projects to use the new release tag. If any issues arise
    from integration, apply any necessary hot fixes to `v$VER.x`
    branch and go back to step 2 - to create a patch release. This step can also be tested
    using `rc` version, potentially followed by another `rc` tag.
 
 ## Make a release locally
 
-Do changes for a release:
-- Start of appropriate branch:
+Prepare changes for the release:
+- Start of appropriate up-to-date branch:
+  - Fetch remotes
+    - `git remote update`
   - For patch release, do it from a stable branch:
     - `git checkout v$VER.x` (e.g., checkout `v0.1.x` if this is a `v0.1.1` patch)
     - If previously we decided not to create such branch, create it now, based on the appropriate minor or major tag
   - For major/minor release start from the `main` branch
-- Add an entry to ChangeLog, remember to change the day of the week in the release date
-  - For major and minor (prior 1.0.0) releases mention API and ABI compatibility with the previous release
+- Add a new entry to the `ChangeLog`, remember to change the day of the week in the release date
+  - For major releases mention API and ABI compatibility with the previous releases
 - For major and minor releases, update `UMF_VERSION_CURRENT` in `include/umf/base.h` (the API version)
   - For changes in ops structures, update corresponding UMF_*_OPS_VERSION_CURRENT
-- For major and minor (prior 1.0.0) releases update ABI version in `.map` and `.def` files
+- For major and minor releases update ABI version in `.map` and `.def` files
   - These files are defined for all public libraries (`libumf` and `proxy_lib`, at the moment)
+  - For minor releases acceptable is only adding new functions/symbols!
+- Once all changes are done, build locally (and/or verify changes on CI), including:
+  - Verify if scanners/linters/checkers passed
+  - Verify if version is set properly, especially in `.dll` and `.so` files
 - Commit these changes and tag the release:
   - `git commit -a -S -m "$VERSION release"`
   - `git tag -a -s -m "Version $VERSION" v$VERSION`
+- Verify if commit and tag are properly signed:
+  - `git verify-commit <commit's sha>`
+  - `git verify-tag v$VERSION`
 - For major/minor release:
   - If stable branch for this release is required, create it:
     - `git checkout -b v$VER.x`
-    - For some early versions (like `0.1.0`) we may omit creation of the branch
+    - For some short-lived versions, creation of this branch may be skipped
 - For major/minor release, when release is done, add an extra "dev" tag on the `main` branch:
-  - `git tag -a -s -m "Development version $VERSION+1" v$VERSION+1-dev`
-    - for example, when `v0.1.0` is released, the dev tag would be `v0.2.0-dev`
-    - if needed, further in time, an extra dev tag can be introduced, e.g. `v0.2.0-dev1`
+  - `git tag -a -s -m "Development version $VERSION+1 - dev1" v$VERSION+1-dev1`
+    - for example, when `v0.1.0` is released, the dev tag would be `v0.2.0-dev1`
+    - if needed, further in time, an extra dev tag can be introduced, e.g. `v0.2.0-dev2`
   - This way, the `main` branch will introduce itself as the next version
+  - "dev" tag can and should be added right after we merge changes from stable to main
 
 ## Publish changes
 
 As patch releases should be done on the stable branches, pushing tags and branches differ a little.
 
+**Note:**
+> Before pushing to "upstream" it's preferred to push changes into your own fork.
+> This allows you to verify the branch and tag manually in GitHub interface, and it will
+> trigger the CI on your fork.
+
 For patch release:
   - `git push upstream HEAD:v$VER.x v$VERSION` - push branch and tag
 
@@ -70,13 +86,17 @@ For major/minor release:
     - `git checkout v$VER.x`
     - `git push upstream HEAD:v$VER.x`
 
+When final release is done it's best to merge back changes from stable branch to main.
+This situation can happen if the stable branch was created before the final release (e.g.
+with one of the RC versions). Thanks to that all the changes, including ChangeLog will land
+on the main branch. After such merge-back it's advised to add "dev" tag (described above).
+
 ## Announce release
 
 To make the release official:
 - Go to [GitHub's releases tab](https://github.com/oneapi-src/unified-memory-framework/releases/new):
   - Tag version: `v$VERSION`, release title: UMF $VERSION, description: copy entry from ChangeLog and format it with no tabs and no characters limit in line
-  - Prior to version 1.0.0, check the *Set as a pre-release* tick box.
-- Announce the release, where needed
+- Announce the release in all appropriate channels
 
 ## More information