mirror of
https://gitlab.kitware.com/vtk/vtk-m
synced 2024-10-05 01:49:02 +00:00
DOCS: add GitLab issue template new-release.md
It updates the ReleaseProcess.md document to describe our bi-branchial workflow composed by a release branch and master branch It also adds ReleaseHotFix.md which describes how to perform a HotFix onto master/release branch. Signed-off-by: Vicente Adolfo Bolea Sanchez <vicente.bolea@kitware.com>
This commit is contained in:
parent
6c2b0dc421
commit
81076385f7
190
.gitlab/issue_templates/NewRelease.md
Normal file
190
.gitlab/issue_templates/NewRelease.md
Normal file
@ -0,0 +1,190 @@
|
||||
<!--
|
||||
This template is for tracking a release of VTKm. Please replace the
|
||||
following strings with the associated values:
|
||||
|
||||
- `@VERSION@` - replace with base version, e.g., 1.6.0
|
||||
- `@RC@` - for release candidates, replace with "-rc?". For final, replace with "".
|
||||
- `@MAJOR@` - replace with major version number
|
||||
- `@MINOR@` - replace with minor version number
|
||||
|
||||
Please remove this comment.
|
||||
-->
|
||||
## Update VTK-m
|
||||
|
||||
- [ ] Update `release` branch for **vtk-m** and create update branch
|
||||
```
|
||||
git fetch origin
|
||||
git checkout release
|
||||
git merge --ff-only origin/release
|
||||
git submodule update --recursive --init
|
||||
```
|
||||
## Create update branch
|
||||
|
||||
<!-- if @RC@ == "-rc1"
|
||||
- [ ] Bring as a second parent the history of master (Solve conflicts always
|
||||
taking master's version)
|
||||
```
|
||||
git merge --no-ff origin/master
|
||||
```
|
||||
-->
|
||||
|
||||
<!-- Do we have new release notes?
|
||||
- [ ] Craft or update [changelog](#generate-change-log)
|
||||
`docs/changelog/@MAJOR@.@MINOR@/release-notes.md` file.
|
||||
- [ ] Create release notes commit.
|
||||
```
|
||||
git add docs/changelog/@MAJOR@.@MINOR@/release-notes.md
|
||||
git rm docs/changelog/*.md
|
||||
git commit -m 'Add release notes for @VERSION@@RC@'
|
||||
```
|
||||
-->
|
||||
|
||||
- [ ] Create update version commit:
|
||||
|
||||
```
|
||||
# Create branch
|
||||
git checkout -b update-to-v@VERSION@@RC@
|
||||
echo @VERSION@@RC@ > version.txt
|
||||
|
||||
# Create commit with the following template
|
||||
# Nth is counted by the number of tags
|
||||
git commit -m '@VERSION@@RC@ is our Nth official release of VTK-m.
|
||||
|
||||
The major changes to VTK-m from (previous release) can be found in:
|
||||
docs/changelog/@MAJOR@.@MINOR@/release-notes.md' version.txt
|
||||
|
||||
```
|
||||
|
||||
- [ ] `git tag -a -m 'VTKm @VERSION@@RC@' v@VERSION@@RC@ HEAD`
|
||||
- Integrate changes to `release` branch
|
||||
- [ ] Create a MR using the [release-mr script][1]
|
||||
(see [notes](#notes-about-update-mr)).
|
||||
- [ ] Get +1
|
||||
- [ ] `Do: merge`
|
||||
- Push tags
|
||||
- [ ] `git push origin v@VERSION@@RC@`
|
||||
|
||||
## Update Spack
|
||||
- [ ] Update Spack package: https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/vtk-m/package.py
|
||||
|
||||
## Post-release
|
||||
- [ ] Copy the contents of docs/changelog/@MAJOR@.@MINOR@/release-notes.md to
|
||||
the GitLab release.
|
||||
- [ ] Tag new version of the [VTK-m User Guide][2].
|
||||
- [ ] Post an [Email Announcements](#email-announcements) VTK-m mailing list.
|
||||
|
||||
---
|
||||
|
||||
# Annex
|
||||
|
||||
## Generate change log
|
||||
Construct a `docs/changelog/@MAJOR@.@MINOR@/` folder.
|
||||
Construct a `docs/changelog/@MAJOR@.@MINOR@/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 DOESN'T have a period 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.
|
||||
|
||||
## Notes about update-mr
|
||||
|
||||
[`update-mr` script][1] has the following requirements to work:
|
||||
|
||||
1. It needs a token to for authentication (reach @ben.boeckel for this)
|
||||
2. It needs `kwrobot.release.vtkm` to have developer perms in your vtk-m repo.
|
||||
|
||||
Lastly, `update-mr` can be used multiple times with different commit in the same
|
||||
branch.
|
||||
|
||||
## 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.
|
||||
|
||||
Example to compute the number of unique committers
|
||||
```
|
||||
git log --format="%an" v1.4.0..v1.5.0 | sort -u | wc -l
|
||||
```
|
||||
|
||||
Example 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/v@VERSION@) or in the vtkm
|
||||
repository at `docs/@MAJOR@.@MINOR@/release-notes.md`
|
||||
|
||||
1. Core
|
||||
- Core change 1
|
||||
2. ArrayHandle
|
||||
3. Control Environment
|
||||
4. Execution Environment
|
||||
5. Worklets and Filters
|
||||
6. Build
|
||||
7. Other
|
||||
```
|
||||
|
||||
/cc @ben.boeckel
|
||||
|
||||
/cc @vbolea
|
||||
|
||||
/label ~"priority:required"
|
||||
|
||||
[1]: https://gitlab.kitware.com/utils/release-utils/-/blob/master/release-mr.py
|
||||
[2]: https://gitlab.kitware.com/vtk/vtk-m-user-guide
|
55
docs/ReleaseHotFix.md
Normal file
55
docs/ReleaseHotFix.md
Normal file
@ -0,0 +1,55 @@
|
||||
Release HotFix
|
||||
===============
|
||||
|
||||
# HotFix from master branch
|
||||
|
||||
## On a single MR
|
||||
|
||||
You have created a branch from master branch and you have a MR request targeting
|
||||
the __master__ branch.
|
||||
|
||||
You can bring this commit to __release__ by adding to any empty line of the MR
|
||||
description box the following directive.
|
||||
|
||||
```
|
||||
Backport: release
|
||||
```
|
||||
|
||||
This will cherry-pick this commit and push it to __release__ after typing `Do:
|
||||
merge` in a comment.
|
||||
|
||||
You must also make sure that there will not be any merge conflict with the
|
||||
__release__ branch, thus you need to create an additional commit using the following
|
||||
command:
|
||||
|
||||
```
|
||||
git merge --no-ff origin/release
|
||||
```
|
||||
|
||||
This will ensure that backport will be able to push your commit to __release__.
|
||||
|
||||
## On multiple MRs
|
||||
|
||||
1. Create one merge request sourcing your HotFix branch and targeting __master__
|
||||
and merge.
|
||||
|
||||
2. Create one merge request sourcing __master__ and targeting __release__ and merge.
|
||||
|
||||
# HotFix from release branch
|
||||
|
||||
You have created a branch from the __release__ branch and you have a MR request
|
||||
targeting __release__, you can proceed as in a regular MR.
|
||||
|
||||
Every merge in release will be automatically brought to master by the robot
|
||||
using `-s ours` strategy.
|
||||
|
||||
__VERY IMPORTANT__: `-s ours` strategy does not actually bring any change to the
|
||||
target branch, thus if needed you might want to bring the changes
|
||||
from the HotFix to __master__ by creating a another MR which cherry-picks
|
||||
the merge commit in `release` for the given HotFix.
|
||||
|
||||
Use the difference to first parent for the cherry-pick commit:
|
||||
|
||||
```
|
||||
git cherry-pick -m1 -x <HASH OF COMMIT>
|
||||
```
|
@ -1,193 +1,72 @@
|
||||
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
|
||||
## Prologue
|
||||
|
||||
This document is divided in two parts:
|
||||
- A overview of the branching and release scheme used in VTK-m.
|
||||
- A concise instructions to get started with the release process.
|
||||
|
||||
# Craft Release Branch
|
||||
The actual release process can be found at
|
||||
`.gitlab/issue_templates/NewRelease.md`.
|
||||
|
||||
Construct a git branch named `release_X.Y`
|
||||
# Overview of the branching scheme
|
||||
|
||||
## Generate change log
|
||||
Construct a `docs/changelog/X.Y/` folder.
|
||||
Construct a `docs/changelog/X.Y/release-notes.md` file
|
||||
Our current scheme is composed of two branches: release and master.
|
||||
|
||||
Use the following template for `release-notes.md`:
|
||||
While all of the development is performed in the master branch, once in a while
|
||||
when we want to do a release, we tag a commit in master and we push it to the
|
||||
release branch.
|
||||
|
||||
```md
|
||||
VTK-m N Release Notes
|
||||
=======================
|
||||
Also there are times when we want to get _Hotfix_ that affects previous releases
|
||||
to the release branch, in this case we can also push the merge request commit
|
||||
with the fix into the release branch.
|
||||
|
||||
# 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)
|
||||
A not so simple example of how the branching scheme looks like can be found
|
||||
here:
|
||||
|
||||
```git
|
||||
# → git log --graph --decorate --oneline --all
|
||||
|
||||
# Core
|
||||
|
||||
## Core change 1 ##
|
||||
|
||||
changes in core 1
|
||||
|
||||
# ArrayHandle
|
||||
|
||||
# Control Enviornment
|
||||
|
||||
# Execution Environment
|
||||
|
||||
# Execution Environment
|
||||
|
||||
# Worklets and Filters
|
||||
|
||||
# Build
|
||||
|
||||
|
||||
# Other
|
||||
* 2e9230d (master) Merge branch 'update'
|
||||
|\
|
||||
| * 59279dd (HEAD -> release, tag: v1.0.1) v1.0.1 2nd release of VTKm
|
||||
| * b60611b Add release notes for v1.0.1
|
||||
| * 9d26451 Merge branch 'master' into update
|
||||
| |\
|
||||
| |/
|
||||
|/|
|
||||
* | 75137e5 Unrelated commit
|
||||
* | e982be0 Merge branch 'release'
|
||||
|\|
|
||||
| * f2c4eb6 Merge branch 'hotfix' into release
|
||||
| |\
|
||||
| | * c1c2655 Hotfix
|
||||
| |/
|
||||
* | e53df9e Unrelated commit
|
||||
* | ec6b481 Unrelated commit
|
||||
|/
|
||||
* 0742a47 (tag: v1.0.0) v1.0.0 1st release of VTKm
|
||||
* 4fe993c Add release notes for v1.0.0
|
||||
```
|
||||
|
||||
For each individual file in `docs/changelog` move them
|
||||
to the relevant `release-notes` section.
|
||||
This will make the release branch to only contain tags and _HotFix_ merges as
|
||||
shown in here:
|
||||
|
||||
- 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.
|
||||
```git
|
||||
# git log --graph --decorate --oneline --first-parent release
|
||||
|
||||
## 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
|
||||
* 59279dd (HEAD -> release, tag: v1.0.1) v1.0.1 2nd release of VTKm
|
||||
* b60611b Add release notes for v1.0.1
|
||||
* 9d26451 Merge branch 'master' into update
|
||||
* f2c4eb6 Merge branch 'hotfix' into release
|
||||
* 0742a47 (tag: v1.0.0) v1.0.0 1st release of VTKm
|
||||
* 4fe993c Add release notes for v1.0.0
|
||||
```
|
||||
|
||||
## Commit update to version.txt
|
||||
# Get started with a new Release
|
||||
|
||||
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
|
||||
```
|
||||
1. Go to `https://gitlab.kitware.com/vtkm/vtk-m/` and open a new issue.
|
||||
2. At the _issue template_ dropdown menu select: `NewRelease.md`
|
||||
3. Now remove the comments and substitute the variables surrounded by `@`.
|
||||
4. Post the issue and follow the steps.
|
||||
|
Loading…
Reference in New Issue
Block a user