<!--
This template is for tracking a release of Viskores.

Process this file with the pyexpander script specifying the desired `version`:

expander.py --eval 'version="1.9.0-rc1"' docs/NewRelease.md.tmpl | xclip -selection c

Please remove this comment.
-->
$py(VERSION=str(version.partition("-")[0]))\
$py(MAJOR=int(VERSION.split(".")[0]))\
$py(MINOR=int(VERSION.split(".")[1]))\
$py(PATCH=int(VERSION.split(".")[2]))\
$py(RC="".join(version.partition("-")[1:3]))\
$if(PATCH == 0 and RC == "")\
## Prerequisites

- [ ] Make sure that the current Viskores release branch builds in VTK.
- [ ] Make sure that the current Viskores release branch builds in ECP Ascent.

$endif\
## Update Viskores

- [ ] Update `release` branch for **viskores** and create update branch
```
git fetch origin
git checkout release
git merge --ff-only origin/release
git submodule update --recursive --init
```
$if(PATCH == 0 and RC == "-rc1")\
- [ ] Update `master` branch for **viskores** and create update branch
```
git fetch origin
git checkout master
git merge --ff-only origin/master
git submodule update --recursive --init
```
$endif\

## Create update branch

- [ ] Freeze the release branch (In Gitlab Viskores page)
  - Settings/Repository/Protected Branches: Release; "allowed to push:No one"
- [ ] Create update branch `git checkout -b update-to-$(VERSION)`
$if(PATCH == 0 and RC == "-rc1")\
- [ ] Bring as a second parent the history of master (Solve conflicts always
      taking master's version)
```
git merge --no-ff origin/master
```
$else\
- [ ] Backport merge-requests belonging to the milestone $(VERSION)
$endif\
$if(PATCH == 0)\
- [ ] Set version to master
```
echo "$(MAJOR).$(MINOR).9999" > version.txt
git add version.txt
```
$endif\

- [ ] Update the version (not in patch releases) and date in the LICENSE.md
      file `git add LICENSE.md`.
- [ ] Create commit that updates the License (and version.txt if modified):
```
git commit -m 'release: update version and License'
```

<!-- Do we have new release notes? -->
- [ ] Craft or update [changelog](#generate-change-log)
      `docs/changelog/$(VERSION)/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 'release: $(VERSION)$(RC) release notes'
```
<!-- endif -->
- [ ] Create update version commit:

```
echo $(VERSION)$(RC) > version.txt
git add version.txt

# Create commit with the following template
# Nth is counted by the number of final release tags
git commit -m '$(VERSION)$(RC) is our Nth official release of Viskores.

The major changes to Viskores from (previous release) can be found in:
  docs/changelog/$(VERSION)/release-notes.md' version.txt
```

- [ ] `git tag -a -m 'Viskores $(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)).
$if(PATCH == 0)\
  - [ ] Add (or ensure) at the bottom of the description of the merge request:
        `Backport: master:HEAD~1`
$else\
  - [ ] Remove (or ensure) that at the bottom of the description of the merge
        request there is no `Backport` instruction.
$endif\
  - [ ] Get +1
  - [ ] `Do: merge`
- Push tags
  - [ ] `git push origin v$(VERSION)$(RC)`
- [ ] Unfreeze the release branch (In Gitlab Viskores page)
  - Settings/Repository/Protected Branches: Release; "allowed to push: Maintainers"

## Update Packages
- [ ] Update Spack package: https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/viskores/package.py
- [ ] Update Conda-forge package: https://github.com/conda-forge/viskores-feedstock
$if(RC == "")\
- [ ] Update OBS package: https://build.opensuse.org/package/show/science/viskores
$endif\

## Post-release
$if(PATCH == 0 and RC == "-rc1")\
- [ ] Create a release-specific branch of the previous major/minor release (Ask
      @ben.boeckel). For more information on release-specific branch maintanance
      schedule refer to `docs/ReleaseRoadmap.md`.
$endif\
- [ ] Copy the contents of docs/changelog/$(VERSION)/release-notes.md to
      the GitLab release.
$if(PATCH == 0 and RC == "")\
- [ ] Tag new version of the [Viskores User Guide][2].
$endif\
- [ ] Post an [Email Announcements](#email-announcements) Viskores mailing list.
$if(RC == "")\
- [ ] Update this release Date, Delay and End-of-Support fields in `docs/ReleaseRoadmap.md`.
$endif\
$if(PATCH == 0)\
- [ ] Ensure that the content of `version.txt` in master is `$(MAJOR).$(MINOR).9999`.
$endif\

## Update Viskores in VTK

VTK ships a particular Viskores release in each of its releases, we need to open a
merge-request update the Viskores commit in VTK as soon as possible even if the
newly Viskores version does not correspond with the scheduled for the following VTK
release, the reason for opening the merge-request is that:

- We can test how compatible it is with VTK giving us the change to address
  those issues in the following releases.
- We do not forget to update Viskores commit in VTK when the time comes

 - [ ] Update Viskores submodule in VTK using: `git submodule update --remote`

---

# Annex

## Generate change log
Construct a `docs/changelog/$(VERSION)/` folder.
Construct a `docs/changelog/$(VERSION)/release-notes.md` file

Use the following template for `release-notes.md`:

```md
Viskores N Release Notes
=======================

<!-- if is a patch release -->

| Merge request description                                           | Merge request id |
| ------------------------------------------------------------------- | ---------------- |
| Update the link to register with the Viskores dashboard                | !2629            |
.
.
.
| CMAKE: CUDA ampere generate sm_80/86                                | !2688            |

<!-- else -->

# 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)

<!-- endif -->
# 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 viskores names
    `viskores::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
    Viskores 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.viskores` to have developer perms in your viskores repo.

Lastly, `update-mr` can be used multiple times with different commit in the same
branch.

## Notes about version.txt

Master and release branch do not share the same version.txt scheme. In the
release branch the patch and release-candidate version is observed whereas in
master the patch field is fixed to _9999_ indicating that each of its commit is
a developing release.

- Master:  `$(MAJOR).$(MINOR).9999`
- Release: `$(MAJOR).$(MINOR).$(PATCH)$(RC)`

## Email Announcements

Announce the new Viskores 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 v2.0.0..v2.1.0 | grep 'Merge topic' | wc -l
```

A standard template to use is:


```
Hi All,

Viskores 1.5.0 is now released, and a special thanks to everyone that has
contributed to Viskores 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://github.com/Viskores/viskores/-/tags/v$(VERSION)) or in the viskores
repository at `docs/$(VERSION)/release-notes.md`

$if(int(PATCH) > 0)\
- changelog title 1
- changelog title 2
- changelog title 3
$else\
1. Core
    - Core change 1
2. ArrayHandle
3. Control Environment
4. Execution Environment
5. Worklets and Filters
6. Build
7. Other
$endif\
```

[1]:  https://gitlab.kitware.com/utils/release-utils/-/blob/master/release-mr.py
[2]:  https://github.com/Viskores/viskores-user-guide

@ben.boeckel  
@vbolea  
/label ~"area:release"  
/milestone %"v$(VERSION)"  
/assign @vbolea
