From 78a8c1181cc7a758addf5cb593de04978aa1dd60 Mon Sep 17 00:00:00 2001 From: Roman Cattaneo <1116746+romanc@users.noreply.github.com> Date: Fri, 31 Oct 2025 14:32:10 +0100 Subject: [PATCH 1/3] release checklist and documentation --- .github/PULL_REQUEST_TEMPLATE/README.md | 6 +++++ .../pull_request_template.md} | 0 .github/PULL_REQUEST_TEMPLATE/release.md | 26 +++++++++++++++++++ .github/workflows/docs_build.yaml | 2 +- .github/workflows/docs_deploy.yaml | 2 +- docs/internal/README.md | 3 +++ docs/internal/release.md | 5 ++++ mkdocs.yml | 3 +++ pyproject.toml | 2 +- 9 files changed, 46 insertions(+), 3 deletions(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE/README.md rename .github/{PULL_REQUEST_TEMPLATE.md => PULL_REQUEST_TEMPLATE/pull_request_template.md} (100%) create mode 100644 .github/PULL_REQUEST_TEMPLATE/release.md create mode 100644 docs/internal/README.md create mode 100644 docs/internal/release.md diff --git a/.github/PULL_REQUEST_TEMPLATE/README.md b/.github/PULL_REQUEST_TEMPLATE/README.md new file mode 100644 index 00000000..985dea6d --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/README.md @@ -0,0 +1,6 @@ +# Pull request templates + +- `pull_request_template.md`: The default pull request template. Used for PRs. +- `release.md`: Special template used for releasing a new version of NDSL. + +Note: GitHub has limited support for multiple pull request templates. Most notably, templates can only be [selected by an URL query parameter](https://github.com/orgs/community/discussions/4620) and there's currently [no way to set a title](https://github.com/orgs/community/discussions/63965). diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md similarity index 100% rename from .github/PULL_REQUEST_TEMPLATE.md rename to .github/PULL_REQUEST_TEMPLATE/pull_request_template.md diff --git a/.github/PULL_REQUEST_TEMPLATE/release.md b/.github/PULL_REQUEST_TEMPLATE/release.md new file mode 100644 index 00000000..7c87a3ee --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/release.md @@ -0,0 +1,26 @@ +# Release NDSL version `2025.XX.00` + +## Pre-release checklist + +Things to do before the release. Helps to keep the fallout from a release as minimal as possible. + +- [ ] setup a draft PR in [NOAA-GFDL/pace](https://github.com/NOAA-GFDL/pace) with updated submodules for `NDSL`, `pyFV3`, and `pySHiELD`. + Don't merge yet - just let CI run and fix potential issues before the release. To be merged afterwards, see post-release checklist. + +## Release checklist + +What to do to actually release: + +- [x] create this PR to merge changes from `develop` into `main` + - merge as "Merge commit" +- [ ] once merged, create a GitHub release and tag the new version + - version format is `[year].[month].[patch]`, e.g. `2025.10.00` + - let GitHub auto-generate release notes from the last tagged version +- [ ] send an announcement on Mattermost + +## Post-release checklist + +What to do after a release: + +- [ ] update the pace PR from the pre-commit checklist to include the released version of NDSL and merge it. +- [ ] merge breaking changes in NDSL (e.g. search for deprecation warnings) diff --git a/.github/workflows/docs_build.yaml b/.github/workflows/docs_build.yaml index 3b0f1ed1..4b59ed78 100644 --- a/.github/workflows/docs_build.yaml +++ b/.github/workflows/docs_build.yaml @@ -28,7 +28,7 @@ jobs: python-version: '3.11' - name: Install mkdocs - run: pip install mkdocs-material mkdocstrings[python] + run: pip install mkdocs-material mkdocstrings[python] mkdocs-exclude - name: Build docs run: mkdocs build diff --git a/.github/workflows/docs_deploy.yaml b/.github/workflows/docs_deploy.yaml index 1e6659d3..cbbb381c 100644 --- a/.github/workflows/docs_deploy.yaml +++ b/.github/workflows/docs_deploy.yaml @@ -29,7 +29,7 @@ jobs: python-version: 3.11 - name: Install dependencies - run: pip install mkdocs-material mkdocstrings[python] + run: pip install mkdocs-material mkdocstrings[python] mkdocs-exclude - name: Deploy docs to GitHub Pages run: mkdocs gh-deploy --force diff --git a/docs/internal/README.md b/docs/internal/README.md new file mode 100644 index 00000000..d8eea9dc --- /dev/null +++ b/docs/internal/README.md @@ -0,0 +1,3 @@ +# Internal documentation + +This folder contains internal / developer documentation and processes, e.g. how to build a release. This folder is thus ignored when building the public facing documentation from the `docs/` folder. diff --git a/docs/internal/release.md b/docs/internal/release.md new file mode 100644 index 00000000..10517a62 --- /dev/null +++ b/docs/internal/release.md @@ -0,0 +1,5 @@ +# Release a new version + +This internal documentation guides you through the process of releasing a new version of NDSL. It is very simple: + +1. Click [create a release](https://github.com/NOAA-GFDL/NDSL/compare/main...develop?expand=1&template=release.md) and follow the steps in the release checklist. diff --git a/mkdocs.yml b/mkdocs.yml index 60fc8e6a..4c385bd1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -146,6 +146,9 @@ plugins: paths: [./ndsl] # Adjust this path to where your Python modules are options: show_source: false + - exclude: + glob: + - internal/* watch: # reload when the glossary file is updated diff --git a/pyproject.toml b/pyproject.toml index cf8e0a69..f05bb3b2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,7 +23,7 @@ requires-python = ">=3.11,<3.12" [project.optional-dependencies] demos = ["ipython", "ipykernel"] dev = ["ndsl[docs]", "ndsl[demos]", "ndsl[test]", "pre-commit", "flake8-pyproject", "build"] -docs = ["mkdocs-material", "mkdocstrings[python]"] +docs = ["mkdocs-material", "mkdocstrings[python]", "mkdocs-exclude"] extras = ["ndsl[docs]", "ndsl[demos]", "ndsl[test]", "ndsl[dev]"] test = ["pytest", "coverage"] From 973c5e9c91fac0cd0a5aa354c3592f02844c6dc5 Mon Sep 17 00:00:00 2001 From: Roman Cattaneo <1116746+romanc@users.noreply.github.com> Date: Fri, 31 Oct 2025 16:08:56 +0100 Subject: [PATCH 2/3] Add template for patch release --- .github/PULL_REQUEST_TEMPLATE/README.md | 1 + .../PULL_REQUEST_TEMPLATE/release-patch.md | 32 +++++++++++++++++++ .github/PULL_REQUEST_TEMPLATE/release.md | 2 +- docs/internal/release.md | 19 +++++++++++ 4 files changed, 53 insertions(+), 1 deletion(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE/release-patch.md diff --git a/.github/PULL_REQUEST_TEMPLATE/README.md b/.github/PULL_REQUEST_TEMPLATE/README.md index 985dea6d..618d2e17 100644 --- a/.github/PULL_REQUEST_TEMPLATE/README.md +++ b/.github/PULL_REQUEST_TEMPLATE/README.md @@ -2,5 +2,6 @@ - `pull_request_template.md`: The default pull request template. Used for PRs. - `release.md`: Special template used for releasing a new version of NDSL. +- `release-patch.md`: Special template used for patch releases. Note: GitHub has limited support for multiple pull request templates. Most notably, templates can only be [selected by an URL query parameter](https://github.com/orgs/community/discussions/4620) and there's currently [no way to set a title](https://github.com/orgs/community/discussions/63965). diff --git a/.github/PULL_REQUEST_TEMPLATE/release-patch.md b/.github/PULL_REQUEST_TEMPLATE/release-patch.md new file mode 100644 index 00000000..c596b9eb --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/release-patch.md @@ -0,0 +1,32 @@ +# Release NDSL version `2025.XX.YY` + +This PR patches release `2025.XX.YY` because + +1. reason +2. reason +3. ... + +## Pre-release checklist + +Things to do before the patch release. Helps to keep the fallout from this release as minimal as possible. + +- [ ] setup a draft PR in [NOAA-GFDL/pace](https://github.com/NOAA-GFDL/pace) with updated submodules for `NDSL`, `pyFV3`, and `pySHiELD`. + Don't merge yet - just let CI run and fix potential issues before the release. To be merged afterwards, see post-release checklist. + +## Release checklist + +What to do to actually release: + +- [x] create this PR to merge changes from `your-hotfix-branch` into `main` + - merge as "Merge commit" +- [ ] once merged, create a GitHub release and tag the new version + - version format is `[year].[month].[patch]`. Increase the patch version, e.g. `2025.10.01` if this is patching the `2025.10.00` release. + - let GitHub auto-generate release notes from the last tagged version +- [ ] send an announcement on Mattermost + +## Post-release checklist + +What to do after a release: + +- [ ] update the pace PR from the pre-commit checklist to include the released version of NDSL and merge it. +- [ ] in NDSL, merge `main` back into `develop` (potentially adding a commit to fix the issue "properly") diff --git a/.github/PULL_REQUEST_TEMPLATE/release.md b/.github/PULL_REQUEST_TEMPLATE/release.md index 7c87a3ee..3d565e22 100644 --- a/.github/PULL_REQUEST_TEMPLATE/release.md +++ b/.github/PULL_REQUEST_TEMPLATE/release.md @@ -2,7 +2,7 @@ ## Pre-release checklist -Things to do before the release. Helps to keep the fallout from a release as minimal as possible. +Things to do before the release. Helps to keep the fallout from this release as minimal as possible. - [ ] setup a draft PR in [NOAA-GFDL/pace](https://github.com/NOAA-GFDL/pace) with updated submodules for `NDSL`, `pyFV3`, and `pySHiELD`. Don't merge yet - just let CI run and fix potential issues before the release. To be merged afterwards, see post-release checklist. diff --git a/docs/internal/release.md b/docs/internal/release.md index 10517a62..7b804a82 100644 --- a/docs/internal/release.md +++ b/docs/internal/release.md @@ -3,3 +3,22 @@ This internal documentation guides you through the process of releasing a new version of NDSL. It is very simple: 1. Click [create a release](https://github.com/NOAA-GFDL/NDSL/compare/main...develop?expand=1&template=release.md) and follow the steps in the release checklist. + +## Patch release + +Every now and then, we'll need to patch the currently released version of NDSL. To do so, follow these steps: + +1. Create a branch from `main`. +2. Commit your changes on that branch. +3. Use the following URL and follow the steps in the patch release checklist. + +As an example, you'd go and create branch `my-patches` from `main` + +```bash +git checkout main +git switch -c my-patches +# do changes ... +git push +``` + +and in that case, the URL with the patch release template is: . From 70341a1064e64cf168c5480404fd0a20fa2e7f67 Mon Sep 17 00:00:00 2001 From: Roman Cattaneo <1116746+romanc@users.noreply.github.com> Date: Mon, 3 Nov 2025 10:11:30 +0100 Subject: [PATCH 3/3] review --- .github/PULL_REQUEST_TEMPLATE/release-patch.md | 8 ++++---- .github/PULL_REQUEST_TEMPLATE/release.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/release-patch.md b/.github/PULL_REQUEST_TEMPLATE/release-patch.md index c596b9eb..c588dd8f 100644 --- a/.github/PULL_REQUEST_TEMPLATE/release-patch.md +++ b/.github/PULL_REQUEST_TEMPLATE/release-patch.md @@ -1,6 +1,6 @@ -# Release NDSL version `2025.XX.YY` +# Release NDSL version `YYYY.MM.PP` -This PR patches release `2025.XX.YY` because +This PR patches release `YYYY.MM.PP` because 1. reason 2. reason @@ -17,8 +17,8 @@ Things to do before the patch release. Helps to keep the fallout from this relea What to do to actually release: -- [x] create this PR to merge changes from `your-hotfix-branch` into `main` - - merge as "Merge commit" +- [x] create this PR to merge changes from `my-patches` into `main` + - use "squash merge" - [ ] once merged, create a GitHub release and tag the new version - version format is `[year].[month].[patch]`. Increase the patch version, e.g. `2025.10.01` if this is patching the `2025.10.00` release. - let GitHub auto-generate release notes from the last tagged version diff --git a/.github/PULL_REQUEST_TEMPLATE/release.md b/.github/PULL_REQUEST_TEMPLATE/release.md index 3d565e22..00aa3403 100644 --- a/.github/PULL_REQUEST_TEMPLATE/release.md +++ b/.github/PULL_REQUEST_TEMPLATE/release.md @@ -1,4 +1,4 @@ -# Release NDSL version `2025.XX.00` +# Release NDSL version `YYYY.MM.00` ## Pre-release checklist