diff --git a/docs/ReleaseProcess.md b/docs/ReleaseProcess.md new file mode 100644 index 000000000..ea5024af6 --- /dev/null +++ b/docs/ReleaseProcess.md @@ -0,0 +1,193 @@ +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 +```