Skip to content

Commit 2054d40

Browse files
[Doc] Add a release guide and an empty ChangeLog file
The release guide is partially based on guides in pmem/pmemkv and pmem/pmdk repos.
1 parent 7f18587 commit 2054d40

File tree

2 files changed

+91
-0
lines changed

2 files changed

+91
-0
lines changed

ChangeLog

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<day of week> <month> <day> 2024 <Author> <[email protected]>
2+
3+
* Version 0.1.0
4+
5+
This is the first release of Unified Memory Framework project.
6+
7+
...

RELEASE_STEPS.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
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 = new full version (e.g., 0.1.0-rc1) # -rc1 included just as an example
8+
set $VER = new major+minor only version (e.g., 0.1)
9+
```
10+
11+
**Note:**
12+
> Before doing the final release, it's recommended to prepare a pre-release version - a "release candidate"
13+
> (or "rc" in short). This requires adding, e.g., `-rc1` to the VERSION string. When all tests and checks
14+
> end properly, you can follow up with the final release. If any fix is required, it should be included in
15+
> another rc version (e.g., `-rc2`).
16+
17+
At the moment, UMF releases are aligned with oneAPI releases - at least one UMF version
18+
will be released for a oneAPI release. Once all changes planned for UMF release are accepted,
19+
we follow the process (described in more detail below):
20+
21+
1. Checkout the appropriate branch (`main` or "stable" `v$VER.x`).
22+
2. Make changes for the release.
23+
3. Create a new tag based on the latest commit - it takes the form
24+
`v<major>.<minor>.<patch>` (e.g., `v0.1.0`).
25+
4. Push the tag and branch to the upstream.
26+
5. Create a new GitHub release using the tag created in the previous step.
27+
6. Update downstream projects to utilize the release tag. If any issues arise
28+
from integration, apply any necessary hot fixes to `v$VER.x`
29+
branch and go back to step 2 - to create a patch release. This step can also be tested
30+
using `rc` version, potentially followed by another `rc` tag.
31+
32+
## Make a release locally
33+
34+
Do changes for a release:
35+
- Start of appropriate branch:
36+
- For patch release, do it from a stable branch:
37+
- `git checkout v$VER.x` (e.g., checkout `v0.1.x` if this is a `v0.1.1` patch)
38+
- If previously we decided not to create such branch, create it now, based on the appropriate minor or major tag
39+
- For major/minor release start from the `main` branch
40+
- Add an entry to ChangeLog, remember to change the day of the week in the release date
41+
- For major releases mention API and ABI compatibility with the previous release
42+
- Update project's version in a few places:
43+
- Set the new $VERSION in `project` function in the top-level `CMakeLists.txt`
44+
- `release` variable in `scripts/docs_config/conf.py` (for docs)
45+
- `UMF_VERSION` variable in `.github/workflows/basic.yml` (for installation test)
46+
- For major releases update ABI version in `.map` and `.def` files
47+
- These files are defined for all public libraries (`libumf` and `proxy_lib`, at the moment)
48+
- Commit these changes and tag the release:
49+
- `git commit -a -S -m "$VERSION release"`
50+
- `git tag -a -s -m "Version $VERSION" v$VERSION`
51+
- For major/minor release:
52+
- If stable branch for this release is required, create it:
53+
- `git checkout -b v$VER.x`
54+
- For some early versions (like `0.1.0`) we may omit creation of the branch
55+
56+
## Publish changes
57+
58+
As patch releases should be done on the stable branches, pushing tags and branches differ a little.
59+
60+
For patch release:
61+
- `git push upstream HEAD:v$VER.x v$VERSION` - push branch and tag
62+
63+
For major/minor release:
64+
- Push main:
65+
- `git push upstream HEAD:main v$VERSION`
66+
- And, if stable branch was also created, push it as well:
67+
- `git checkout v$VER.x`
68+
- `git push upstream HEAD:v$VER.x`
69+
70+
## Announce release
71+
72+
To make the release official:
73+
- Go to [GitHub's releases tab](https://github.com/oneapi-src/unified-memory-framework/releases/new):
74+
- 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
75+
- Prior to version 1.0.0, check the *Set as a pre-release* tick box.
76+
- Announce the release, where needed
77+
78+
## More information
79+
80+
To assure the community that the release is a valid package from UMF maintainers, it's recommended to sign the release
81+
commit and the tag (`-S`/`-s` parameters in commands above). If you require to generate a GPG key follow
82+
[these steps](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key).
83+
After that you'd also have to add this new key to your GitHub account - please do the steps in
84+
[this guide](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key).

0 commit comments

Comments
 (0)