mirror of
https://gitlab.kitware.com/vtk/vtk-m
synced 2024-09-16 17:22:55 +00:00
194 lines
4.8 KiB
Markdown
194 lines
4.8 KiB
Markdown
|
Release Process
|
||
|
===============
|
||
|
|
||
|
# High level view
|
||
|
1. Craft Release Branch
|
||
|
- Generate change log
|
||
|
- Commit change log
|
||
|
- Commit update to version.txt
|
||
|
- Merge release branch
|
||
|
2. Tag release
|
||
|
3. Add Gitlab Release Notes
|
||
|
4. Announce
|
||
|
|
||
|
|
||
|
# Craft Release Branch
|
||
|
|
||
|
Construct a git branch named `release_X.Y`
|
||
|
|
||
|
## Generate change log
|
||
|
Construct a `docs/changelog/X.Y/` folder.
|
||
|
Construct a `docs/changelog/X.Y/release-notes.md` file
|
||
|
|
||
|
Use the following template for `release-notes.md`:
|
||
|
|
||
|
```md
|
||
|
VTK-m N Release Notes
|
||
|
=======================
|
||
|
|
||
|
# Table of Contents
|
||
|
1. [Core](#Core)
|
||
|
- Core change 1
|
||
|
2. [ArrayHandle](#ArrayHandle)
|
||
|
3. [Control Environment](#Control-Environment)
|
||
|
4. [Execution Environment](#Execution-Environment)
|
||
|
5. [Worklets and Filters](#Worklets-and-Filters)
|
||
|
6. [Build](#Build)
|
||
|
7. [Other](#Other)
|
||
|
|
||
|
|
||
|
# Core
|
||
|
|
||
|
## Core change 1 ##
|
||
|
|
||
|
changes in core 1
|
||
|
|
||
|
# ArrayHandle
|
||
|
|
||
|
# Control Enviornment
|
||
|
|
||
|
# Execution Environment
|
||
|
|
||
|
# Execution Environment
|
||
|
|
||
|
# Worklets and Filters
|
||
|
|
||
|
# Build
|
||
|
|
||
|
|
||
|
# Other
|
||
|
```
|
||
|
|
||
|
For each individual file in `docs/changelog` move them
|
||
|
to the relevant `release-notes` section.
|
||
|
|
||
|
- Make sure each title and entry in the table of contents use full vtkm names `vtkm::cont::Field` instead of Field
|
||
|
- Make sure each title and entry DOESNT have a peroid at the end
|
||
|
- Make sure any sub-heading as part of the changelog is transformed from `##` to `###`.
|
||
|
- Entries for `Core` are reserved for large changes that significantly improve VTK-m users life, or are
|
||
|
major breaking changes.
|
||
|
|
||
|
## Commit change log
|
||
|
|
||
|
Remove each individual change log file from the git repository
|
||
|
using `git rm docs/changelog/*.md`
|
||
|
|
||
|
Add the changelog to the git history using `git add changelog/X.Y/release-notes.md`
|
||
|
|
||
|
make a commit with the message:
|
||
|
```
|
||
|
Add release notes for vX.Y.Z
|
||
|
```
|
||
|
|
||
|
## Commit update to version.txt
|
||
|
|
||
|
Add a second commit to the `release_X.Y` branch that contains the update
|
||
|
of the `version.txt` file to the correct version. The commit diff should look like:
|
||
|
```
|
||
|
--- a/version.txt
|
||
|
+++ b/version.txt
|
||
|
@@ -1 +1 @@
|
||
|
-1.4.0
|
||
|
+1.5.0
|
||
|
```
|
||
|
|
||
|
The commit message should read:
|
||
|
```
|
||
|
X.Y.0 is our Nth official release of VTK-m.
|
||
|
|
||
|
The major changes to VTK-m from A.B.C can be found in:
|
||
|
docs/changelog/X.Y/release-notes.md
|
||
|
```
|
||
|
|
||
|
## Merge release branch
|
||
|
|
||
|
At this point you should be ready to merge this branch.
|
||
|
So push to the `release_X.Y` branch to gitlab and open a merge request.
|
||
|
The dashboards should produce a configure warning that the new release git tag
|
||
|
can't be found. This is to be expected.
|
||
|
|
||
|
Before completing the merge it is a good idea to review the rendered markdown of the release notes to ensure that they display properly.
|
||
|
On the merge request page, click on the Changes tab and then for the `release.X.Y` file click the View file button in the upper right.
|
||
|
|
||
|
# Tag Release
|
||
|
|
||
|
Once the merge request is merged we can add the tag.
|
||
|
VTK-m marks the commit that contains the modifications to `version.txt` as the tag location, not the merge commit.
|
||
|
After the merge this would be the second commit shown by git log as shown below:
|
||
|
|
||
|
```
|
||
|
git checkout master
|
||
|
git pull
|
||
|
git log -n2
|
||
|
Merge: d3d3e441 f66d980d
|
||
|
commit f66d980d (HEAD -> release_X.Y.0, gitlab/release_X.Y.0, master)
|
||
|
```
|
||
|
|
||
|
To place the tag at the correct location you will use the following command:
|
||
|
```
|
||
|
git tag -a -f vX.Y.Z SHA1
|
||
|
```
|
||
|
|
||
|
For the above example the `SHA1` would be `f66d980d`
|
||
|
|
||
|
This should prompt you to add a message to the tag. The message should be identical to the one
|
||
|
you used in the commit.
|
||
|
|
||
|
## Push git tags
|
||
|
|
||
|
Now you will need to push the tag back to gitlab so you will need to do the following:
|
||
|
|
||
|
```
|
||
|
git remote add origin_update_tags git@gitlab.kitware.com:vtk/vtk-m.git
|
||
|
git push --tags origin_update_tags
|
||
|
git remote rm origin_update_tags
|
||
|
|
||
|
```
|
||
|
|
||
|
# Add Gitlab Release Notes
|
||
|
|
||
|
Now that the VTK-m release is on gitlab we have to add the associated changelog to the release
|
||
|
entry on gitlab.
|
||
|
|
||
|
Go to `https://gitlab.kitware.com/vtk/vtk-m/-/tags/vX.Y.Z/release/edit` to edit the release page.
|
||
|
Copy the contents of `docs/changelog/X.Y/release-notes.md`
|
||
|
|
||
|
# Email Announcements
|
||
|
|
||
|
Announce the new VTK-m release on the mailing list. You will need to compute
|
||
|
the number of merge requests, changelog entries, and maybe # of authors.
|
||
|
|
||
|
To compute the number of unique committers
|
||
|
```
|
||
|
git log --format="%an" v1.4.0..v1.5.0 | sort -u | wc -l
|
||
|
```
|
||
|
|
||
|
To compute the number of merge requests
|
||
|
```
|
||
|
git log v1.4.0..v1.5.0 | grep 'Merge | wc -l
|
||
|
```
|
||
|
|
||
|
A standard template to use is:
|
||
|
|
||
|
|
||
|
```
|
||
|
Hi All,
|
||
|
|
||
|
VTK-m 1.5.0 is now released, and a special thanks to everyone that has
|
||
|
contributed to VTK-m since our last release. The 1.5.0 release contains
|
||
|
over 100000 merge requests, and 100000 entries to the changelog .
|
||
|
|
||
|
Below are all the entries in the changelog, with more details at (
|
||
|
https://gitlab.kitware.com/vtk/vtk-m/tags/vX.Y.0 ) or in the vtkm
|
||
|
repository at `docs/X.Y/release-notes.md`
|
||
|
|
||
|
1. Core
|
||
|
- Core change 1
|
||
|
2. ArrayHandle
|
||
|
3. Control Environment
|
||
|
4. Execution Environment
|
||
|
5. Worklets and Filters
|
||
|
6. Build
|
||
|
7. Other
|
||
|
```
|