Improve the release checklist based on experience with v0.13.0 release #3374

seisman · 2024-08-05T03:35:43Z

This PR updates the release checklist.

Here are the main changes in this PR:

Add a placeholder for release DOI
Review the "PyGMT Team" as early as possible
Check deprecations before checking CI runs
Simplify the task for working on the changelog entry
Check misspellings as late as possible
Draft the announcement as early as possible
Rename the zip file before uploading to Zenodo
~~Check two options when making a release~~

.github/ISSUE_TEMPLATE/4-release_checklist.md

Co-authored-by: Michael Grund <[email protected]>

.github/ISSUE_TEMPLATE/4-release_checklist.md

Co-authored-by: Yvonne Fröhlich <[email protected]>

.github/ISSUE_TEMPLATE/4-release_checklist.md

seisman · 2024-09-05T12:14:32Z

.github/ISSUE_TEMPLATE/4-release_checklist.md

@@ -10,47 +10,46 @@ assignees: ''
 **Release**: [v0.x.x](https://github.com/GenericMappingTools/pygmt/milestones/?)
 **Scheduled Date**: YYYY/MM/DD
 **Pull request due date**: YYYY/MM/DD
+**DOI**: `10.5281/zenodo.XXXXXXX`


Add the DOI at the top so that we can copy and paste to other files.

seisman · 2024-09-05T12:15:01Z

.github/ISSUE_TEMPLATE/4-release_checklist.md

 - [ ] Check [SPEC 0](https://scientific-python.org/specs/spec-0000/) to see if we need to bump the minimum supported versions of GMT, Python and core package dependencies (NumPy/Pandas/Xarray)
- [ ] Run `make codespell` to check common misspellings. If there are any, either fix them or add them to `ignore-words-list` in `pyproject.toml`
+- [ ] Review the ["PyGMT Team" page](https://www.pygmt.org/dev/team.html)


Review the PyGMT team as early as possible so that we have more time for discussions.

seisman · 2024-09-05T12:16:21Z

.github/ISSUE_TEMPLATE/4-release_checklist.md

 - [ ] Check to ensure that:
+  - [ ] Deprecations and related tests are removed for this version by running `grep --include="*.py" -r vX.Y.Z` from the base of the repository


Check deprecations as early as possible, so that we don't have to check workflow runs after removing deprecated codes and tests.

seisman · 2024-09-05T12:20:26Z

.github/ISSUE_TEMPLATE/4-release_checklist.md

-  - [ ] Add minimum required version information `doc/minversions.md`
-  - [ ] Copy draft changelog from Release Drafter and edit it to look nice ([see maintainers guide for details](https://www.pygmt.org/dev/maintenance.html#updating-the-changelog))
+- [ ] Finish up the "Changelog entry for v0.x.x" Pull Request (Use the previous changelog PR as a reference)
+- [ ] Run `make codespell` to check common misspellings. If there are any, either fix them or add them to `ignore-words-list` in `pyproject.toml`


Check misspelling after finishing the changlog, just in case we introduce new typos in changelog.

seisman · 2024-09-05T12:22:04Z

.github/ISSUE_TEMPLATE/4-release_checklist.md

-  - [ ] Copy draft changelog from Release Drafter and edit it to look nice ([see maintainers guide for details](https://www.pygmt.org/dev/maintenance.html#updating-the-changelog))
+- [ ] Finish up the "Changelog entry for v0.x.x" Pull Request (Use the previous changelog PR as a reference)
+- [ ] Run `make codespell` to check common misspellings. If there are any, either fix them or add them to `ignore-words-list` in `pyproject.toml`
+- [ ] Draft the announcement on https://hackmd.io/@pygmt


Start to draft the announcement when we work on the changelog, so that we can finish the announcement as early as possible after making a release.

seisman · 2024-09-05T12:26:10Z

.github/ISSUE_TEMPLATE/4-release_checklist.md

-  - [ ] Add the documentation link `doc/minversions.md`
-  - [ ] Add minimum required version information `doc/minversions.md`
-  - [ ] Copy draft changelog from Release Drafter and edit it to look nice ([see maintainers guide for details](https://www.pygmt.org/dev/maintenance.html#updating-the-changelog))
+- [ ] Finish up the "Changelog entry for v0.x.x" Pull Request (Use the previous changelog PR as a reference)


Previously, this task has many smaller tasks:

- [ ] Add a new entry in `doc/_static/version_switch.js` for documentation switcher - [ ] Update `CITATION.cff` and BibTeX at https://github.com/GenericMappingTools/pygmt#citing-pygmt - [ ] Update authorship list - [ ] Update DOI (and url for BibTeX) - [ ] Update version - [ ] Update date released - [ ] Add the documentation link `doc/minversions.md` - [ ] Add minimum required version information `doc/minversions.md` - [ ] Copy draft changelog from Release Drafter and edit it to look nice ([see maintainers guide for details](https://www.pygmt.org/dev/maintenance.html#updating-the-changelog))

Based on my experience with making releases, I usually use the previous changelog PR as a reference. For example, when releasing v0.13.0 in #3425, I used the v0.12.0 PR #3201 as reference. I feel we can move these subtasks from the release checklist to the release PR. So, when releasing v0.14.0, we will use #3425 as a reference.

seisman · 2024-09-05T12:27:03Z

.github/ISSUE_TEMPLATE/4-release_checklist.md

 - [ ] At the [PyGMT release page on GitHub](https://github.com/GenericMappingTools/pygmt/releases):
  - [ ] Edit the draft release notes with the finalized changelog
  - [ ] Set the tag version and release title to vX.Y.Z
+  - [ ] Make sure "Set as the latests release" and "Create a discussion for this release" are selected


"Create a discussion for this release" is a new option after we enable the project "Discussions". See https://github.com/GenericMappingTools/pygmt/discussions/3426 for an example.

I don't think we should enable discussions for this repo, best to keep everything on the forum to avoid having too many places to monitor.

Are you suggesting (1) Disabling announcements for releases in the "Discussions" page or (2) Disabling the entire "Discussions" page?

I'm OK with (1). I prefer to keep the "Discussions" page for non-issue discussions. For example, we may need to discuss the expected release date for v0.14.0, but I don't want to open an issue for it; some technical discussions may be better moved to "Discussions" (e.g., #3398).

Are you suggesting (1) Disabling announcements for releases in the "Discussions" page or (2) Disabling the entire "Discussions" page?

I'd prefer (2) actually - disable a PyGMT-specific discussion page. Less things to keep track of 🙂

some technical discussions may be better moved to "Discussions" (e.g., #3398).

Issues/discussions like that are rather rare, but I see your point. I've been thinking if we can convert the GMT repo's discussion at https://github.com/GenericMappingTools/gmt/discussions into an organization-wide discussion (see https://docs.github.com/en/organizations/managing-organization-settings/enabling-or-disabling-github-discussions-for-an-organization), and maybe have a pygmt specific category there? I don't have the permissions to do so though.

The entry is removed in 0708027.

I've been thinking if we can convert the GMT repo's discussion at https://github.com/GenericMappingTools/gmt/discussions into an organization-wide discussion (see https://docs.github.com/en/organizations/managing-organization-settings/enabling-or-disabling-github-discussions-for-an-organization), and maybe have a pygmt specific category there? I don't have the permissions to do so though.

It seems impossible to subscribe to a specific category. I'm also unsure who will be notified when a discussion is created in the "pygmt" category.

seisman · 2024-09-05T12:34:26Z

.github/ISSUE_TEMPLATE/4-release_checklist.md

 - [ ] At the [PyGMT release page on GitHub](https://github.com/GenericMappingTools/pygmt/releases):
  - [ ] Edit the draft release notes with the finalized changelog
  - [ ] Set the tag version and release title to vX.Y.Z
+  - [ ] Make sure "Set as the latests release" and "Create a discussion for this release" are selected
  - [ ] Make a release by clicking the 'Publish Release' button, this will automatically create a tag too
 - [ ] Manually upload the pygmt-vX.Y.Z.zip and baseline-images.zip files to https://zenodo.org/deposit, ensure that it is filed under the correct reserved DOI


@weiji14 One question for you: It seems the zip file downloaded from https://github.com/GenericMappingTools/pygmt/releases/tag/v0.13.0 has a name like pygmt-0.13.0.zip, but the zip file on Zenodo has a name like pygmt-v0.13.0.zip (the extra v). Did you manually rename pygmt-0.13.0.zip to pygmt-v0.13.0.zip when you uploaded previous versions?

Yes, good catch. I always needed to rename it to add an extra 'v'.

Any specific reason for the renaming? The zip file is called pygmt-v0.13.0.zip, but the directory in the zip file is pygmt-0.13.0.zip.

I see that this was included in the original release checklist at f2842c0. Can't remember now since it was 4 years ago, but it might be that our tags follow v0.X.Y, so I decided to use pygmt-v0.X.Y.zip for the filename, and just kept it to be consistent ever since.

Just checked scipy, xarray and pandas on Zenodo. It seems they all zenodo register the DOI after making a release. Taking pandas as an example, the zip file name is pandas-dev/pandas-v2.2.2.zip, and the directory inside is pydata-xarray-da9ff0a. So I guess there is no guide about the best names for the zip file and the directory.

I'll mention the renaming in the checklist.

Edit: Done in 2d979e2.

.github/ISSUE_TEMPLATE/4-release_checklist.md

Co-authored-by: Wei Ji <[email protected]>

.github/ISSUE_TEMPLATE/4-release_checklist.md

seisman added 6 commits August 5, 2024 11:07

Move spelling check to the end of the list

c09cd24

Fix a typo

30c081f

GMT-GS compatability is not in a new separate subsection

ad5fffd

Remove deprecated codes first before checking other CI workflows

13961dc

Add a entry to check pre-commit hooks

ea7c25d

Draft the announcement before the release

4470f96

seisman added this to the 0.14.0 milestone Aug 5, 2024

seisman added the needs review This PR has higher priority and needs review. label Aug 5, 2024

michaelgrund approved these changes Aug 5, 2024

View reviewed changes

.github/ISSUE_TEMPLATE/4-release_checklist.md Outdated Show resolved Hide resolved

Typo

7316504

Co-authored-by: Michael Grund <[email protected]>

yvonnefroehlich reviewed Aug 5, 2024

View reviewed changes

.github/ISSUE_TEMPLATE/4-release_checklist.md Outdated Show resolved Hide resolved

seisman and others added 2 commits August 6, 2024 06:42

Update .github/ISSUE_TEMPLATE/4-release_checklist.md

bbda6c2

Co-authored-by: Yvonne Fröhlich <[email protected]>

Review the PyGMT team page earlier since it may take some time

fcfe59d

seisman removed the needs review This PR has higher priority and needs review. label Aug 13, 2024

seisman commented Aug 25, 2024

View reviewed changes

.github/ISSUE_TEMPLATE/4-release_checklist.md Outdated Show resolved Hide resolved

seisman mentioned this pull request Aug 26, 2024

Add pre-commit.ci configurations to enable auto updates of hooks #3414

Merged

seisman added 2 commits August 27, 2024 17:37

Merge branch 'main' into release-checklist

a403117

No need to check hooks manually after enabling pre-commit.ci

aff71d2

seisman changed the title ~~Release Checklist: Check pre-commit hooks and draft announcement before release~~ Release Checklist: Draft announcement before release Sep 1, 2024

seisman added 2 commits September 4, 2024 13:58

Merge branch 'main' into release-checklist

f506f65

Show DOI at the top

12a2011

seisman removed this from the 0.14.0 milestone Sep 5, 2024

seisman added 5 commits September 5, 2024 09:45

Simplify the checklist for changelog entry

55f27eb

Update the command to check deprecations in this version

fcfd34a

Create a discussion for this release

a4af06e

Merge branch 'main' into release-checklist

be22c85

Check spelling before drafting annoucement

a996ec9

seisman commented Sep 5, 2024

View reviewed changes

seisman changed the title ~~Release Checklist: Draft announcement before release~~ Improve the release checklist based on experience with v0.13.0 release Sep 5, 2024

seisman added the maintenance Boring but important stuff for the core devs label Sep 5, 2024

seisman added skip-changelog Skip adding Pull Request to changelog needs review This PR has higher priority and needs review. labels Sep 5, 2024

seisman added this to the 0.14.0 milestone Sep 5, 2024

seisman marked this pull request as ready for review September 5, 2024 12:30

seisman commented Sep 5, 2024

View reviewed changes

Add instructions to trigger conda-forge's update manually

a6e3e98

seisman commented Sep 5, 2024

View reviewed changes

.github/ISSUE_TEMPLATE/4-release_checklist.md Outdated Show resolved Hide resolved

Fix a typo

d809f74

seisman commented Sep 5, 2024

View reviewed changes

.github/ISSUE_TEMPLATE/4-release_checklist.md Show resolved Hide resolved

Need to rename the zip file before uploading

2d979e2

weiji14 reviewed Sep 6, 2024

View reviewed changes

.github/ISSUE_TEMPLATE/4-release_checklist.md Outdated Show resolved Hide resolved

.github/ISSUE_TEMPLATE/4-release_checklist.md Outdated Show resolved Hide resolved

Apply suggestions from code review

fed3fc9

Co-authored-by: Wei Ji <[email protected]>

seisman commented Sep 6, 2024

View reviewed changes

.github/ISSUE_TEMPLATE/4-release_checklist.md Outdated Show resolved Hide resolved

seisman added 2 commits September 6, 2024 13:39

Do not create a discussion for a release

0708027

Merge branch 'main' into release-checklist

a26795c

seisman requested a review from a team September 9, 2024 23:54

seisman commented Sep 10, 2024

View reviewed changes

.github/ISSUE_TEMPLATE/4-release_checklist.md Outdated Show resolved Hide resolved

Year 20XX

0274d4d

weiji14 approved these changes Sep 10, 2024

View reviewed changes

seisman added final review call This PR requires final review and approval from a second reviewer and removed needs review This PR has higher priority and needs review. labels Sep 10, 2024

seisman merged commit 2bb65df into main Sep 10, 2024
8 checks passed

seisman deleted the release-checklist branch September 10, 2024 22:26

seisman removed the final review call This PR requires final review and approval from a second reviewer label Sep 10, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve the release checklist based on experience with v0.13.0 release #3374

Improve the release checklist based on experience with v0.13.0 release #3374

seisman commented Aug 5, 2024 •

edited

Loading

seisman Sep 5, 2024

seisman Sep 5, 2024

seisman Sep 5, 2024

seisman Sep 5, 2024

seisman Sep 5, 2024

seisman Sep 5, 2024

seisman Sep 5, 2024

weiji14 Sep 6, 2024

seisman Sep 6, 2024 •

edited

Loading

weiji14 Sep 6, 2024 •

edited

Loading

seisman Sep 6, 2024

seisman Sep 5, 2024

weiji14 Sep 5, 2024

seisman Sep 6, 2024

weiji14 Sep 6, 2024

seisman Sep 6, 2024 •

edited

Loading

		- [ ] Check to ensure that:
		- [ ] Deprecations and related tests are removed for this version by running `grep --include="*.py" -r vX.Y.Z` from the base of the repository

Improve the release checklist based on experience with v0.13.0 release #3374

Improve the release checklist based on experience with v0.13.0 release #3374

Conversation

seisman commented Aug 5, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seisman Sep 6, 2024 • edited Loading

Choose a reason for hiding this comment

weiji14 Sep 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seisman Sep 6, 2024 • edited Loading

Choose a reason for hiding this comment

seisman commented Aug 5, 2024 •

edited

Loading

seisman Sep 6, 2024 •

edited

Loading

weiji14 Sep 6, 2024 •

edited

Loading

seisman Sep 6, 2024 •

edited

Loading