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
```