docs: release checklist and documentation

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

.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")

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

.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

.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

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.

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 <https://github.com/NOAA-GFDL/NDSL/compare/main...[your-branch-name]?expand=1&template=release-patch.md> 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: <https://github.com/NOAA-GFDL/NDSL/compare/main...my-patches?expand=1&template=release-patch.md>.

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

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"]