newrelease.md: templatize newrelease.md

- Uses pyexpander as engine since we already depend on it. - Add rules for dealing with VTK releases. - Updates docs/ReleaseProcess.md .
2024-07-06 07:17:25 +00:00 · 2022-09-28 18:02:37 -04:00 · 2022-09-28 18:02:37 -04:00 · 165d6d936f
commit 165d6d936f
parent 7496dc1e9e
3 changed files with 100 additions and 79 deletions
--- a/.gitattributes
+++ b/.gitattributes
@ -10,7 +10,8 @@ data/** filter=lfs diff=lfs merge=lfs -text
 /**/data/** filter=lfs diff=lfs merge=lfs -text

 *.cmake          whitespace=tab-in-indent
-*.md             whitespace=tab-in-indent conflict-marker-size=79 -whitespace
+*.md             whitespace=tab-in-indent whitespace=-blank-at-eol conflict-marker-size=79 -whitespace
+*.md.tmpl        whitespace=tab-in-indent whitespace=-blank-at-eol conflict-marker-size=79 -whitespace
 *.rst            whitespace=tab-in-indent conflict-marker-size=79
 *.txt            whitespace=tab-in-indent

--- a/.gitlab/issue_templates/NewRelease.md
+++ b/.gitlab/issue_templates/NewRelease.md
@ -1,111 +1,132 @@
 <!--
-This template is for tracking a release of VTKm. Please replace the
-following strings with the associated values:
+This template is for tracking a release of VTKm.

-  - `@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
+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]))\
 ## Update VTK-m

-  - [ ] Update `release` branch for **vtk-m** and create update branch
+- [ ] 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
 ```
+$if(PATCH == 0 and RC == "-rc1")\
+- [ ] Update `master` branch for **vtk-m** 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

-  - [ ] Create update branch `git checkout -b update-to-v@VERSION@`
-<!-- if @RC@ == "-rc1"-->
-  - [ ] Bring as a second parent the history of master (Solve conflicts always
-        taking master's version)
+- [ ] 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
+git merge --no-ff origin/master
+echo "$(MAJOR).$(MINOR).9999" > version.txt
+git add version.txt
 ```
-<!-- endif -->
+$else\
+- [ ] Backport merge-requests belonging to the milestone $(VERSION)
+$endif\

-<!-- if not a patch release -->
-  - [ ] Update the major and minor version in `version.txt`:
-```
-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):
+- [ ] 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.
+- [ ] Craft or update [changelog](#generate-change-log)
+      `docs/changelog/$(VERSION)/release-notes.md` file.
+- [ ] Create release notes commit.
 ```
-git add docs/changelog/@VERSION@/release-notes.md
+git add docs/changelog/$(MAJOR).$(MINOR)/release-notes.md
 git rm docs/changelog/*.md
-git commit -m 'release: @VERSION@@RC@ release notes'
+git commit -m 'release: $(VERSION)$(RC) release notes'
 ```
 <!-- endif -->
-  - [ ] Create update version commit:
+- [ ] Create update version commit:

 ```
-echo @VERSION@@RC@ > version.txt
+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 VTK-m.
+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/@VERSION@/release-notes.md' version.txt
+  docs/changelog/$(VERSION)/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)).
-<!-- if not patch release -->
-    - [ ] Add (or ensure) at the bottom of the description of the merge request:
-          `Backport: master:HEAD~1`
-<!-- elseif patch release -->
-    - [ ] 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@`
+- [ ] `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)).
+$if(PATCH == 0 and RC == "-rc1")\
+  - [ ] 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)`

 ## Update Spack
- - [ ] Update Spack package: https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/vtk-m/package.py
+- [ ] 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/@VERSION@/release-notes.md to
-        the GitLab release.
-<!-- if not patch release -->
-  - [ ] Tag new version of the [VTK-m User Guide][2].
-<!-- endif -->
-  - [ ] Post an [Email Announcements](#email-announcements) VTK-m mailing list.
-<!-- if not patch release -->
-  - [ ] Ensure that the content of `version.txt` in master is
-        `[@MAJOR@ @MINOR@](@MAJOR@.@MINOR@.9999)`.
-<!-- endif release -->
+- [ ] Copy the contents of docs/changelog/$(VERSION)/release-notes.md to
+      the GitLab release.
+$if(PATCH == 0 and RC == ""))\
+- [ ] Tag new version of the [VTK-m User Guide][2].
+$endif\
+- [ ] Post an [Email Announcements](#email-announcements) VTK-m mailing list.
+$if(PATCH == 0)\
+- [ ] Ensure that the content of `version.txt` in master is `$(MAJOR).$(MINOR).9999`.
+$endif\
+
+## Update VTK-m in VTK
+
+VTK ships a particular VTK-m release in each of its releases, we need to open a
+merge-request update the VTK-m commit in VTK as soon as possible even if the
+newly VTK-m 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 VTK-m commit in VTK when the time comes
+
+ - [ ] Update VTK-m 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
+Construct a `docs/changelog/$(VERSION)/` folder.
+Construct a `docs/changelog/$(VERSION)/release-notes.md` file

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

@ -186,8 +207,8 @@ 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@`
+- Master:  `$(MAJOR).$(MINOR).9999`
+- Release: `$(MAJOR).$(MINOR).$(PATCH)$(RC)`

 ## Email Announcements

@ -215,18 +236,16 @@ 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/@VERSION@/release-notes.md`
-
-<!-- if is a patch release -->
+https://gitlab.kitware.com/vtk/vtk-m/-/tags/v$(VERSION)) or in the vtkm
+repository at `docs/$(VERSION)/release-notes.md`

+$if(int(PATCH) > 0)\
 - Update the link to register with the VTK-m dashboard
 .
 .
 .
 - CMAKE: CUDA ampere generate sm_80/86
-
-<!-- else -->
+$else\
 1. Core
    - Core change 1
 2. ArrayHandle
@ -235,14 +254,12 @@ repository at `docs/@VERSION@/release-notes.md`
 5. Worklets and Filters
 6. Build
 7. Other
-<!-- endif -->
+$endif\
 ```

-/cc @ben.boeckel
-
-/cc @vbolea
-
-/label ~"priority:required"
+@ben.boeckel  
+@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
--- a/docs/ReleaseProcess.md
+++ b/docs/ReleaseProcess.md
@ -87,6 +87,9 @@ shown in here:
 # Get started with a new Release

 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.
+2. Generate and copy to clipboard the release script (-rcN is optional):
+```
+# Download pyexpander (Available in pip)
+expander.py --eval 'version="X.Y.Z-rcN"' docs/NewRelease.md.tmpl | xclip -selection c
+```
+3. Paste the output in the issue and follow the steps.