diff --git a/.github/PULL_REQUEST_TEMPLATE/README.md b/.github/PULL_REQUEST_TEMPLATE/README.md new file mode 100644 index 00000000..618d2e17 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/README.md @@ -0,0 +1,7 @@ +# 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. +- `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.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-patch.md b/.github/PULL_REQUEST_TEMPLATE/release-patch.md new file mode 100644 index 00000000..c588dd8f --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/release-patch.md @@ -0,0 +1,32 @@ +# Release NDSL version `YYYY.MM.PP` + +This PR patches release `YYYY.MM.PP` 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 `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 +- [ ] 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 new file mode 100644 index 00000000..00aa3403 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/release.md @@ -0,0 +1,26 @@ +# Release NDSL version `YYYY.MM.00` + +## Pre-release checklist + +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. + +## 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..7b804a82 --- /dev/null +++ b/docs/internal/release.md @@ -0,0 +1,24 @@ +# 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. + +## 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: . 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"]