chore: add check for version_next markers (#2542)

In a couple recent PRs, I put "VERSION_NEXT_{feature,patch}" as place
holders since I
wasn't sure what the next appropriate version would be for unreleased
code. e.g.
specifying `1.0.1` becomes invalid if a subsequent PR would make it
`1.1.0`.

To help remind us to populate these values before a release, have the
release workflow
check for the marker strings.

.github/workflows/create_archive_and_notes.sh

@@ -15,6 +15,14 @@
 
 set -o errexit -o nounset -o pipefail
 
+# Exclude dot directories, specifically, this file so that we don't
+# find the substring we're looking for in our own file.
+if grep --exclude-dir=.* VERSION_NEXT_ -r; then
+  echo
+  echo "Found VERSION_NEXT markers indicating version needs to be specified"
+  exit 1
+fi
+
 # Set by GH actions, see
 # https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables
 TAG=${GITHUB_REF_NAME}

CONTRIBUTING.md

@@ -137,19 +137,58 @@ If a breaking change is introduced, then `BREAKING CHANGE:` is required; see
 the [Breaking Changes](#breaking-changes) section for how to introduce breaking
 changes.
 
+User visible changes, such as features, fixes, or notable refactors, should
+be documneted in CHANGELOG.md and their respective API doc. See [Documenting
+changes] for how to do so.
+
 Common `type`s:
 
 * `build:` means it affects the building or development workflow.
 * `docs:` means only documentation is being added, updated, or fixed.
-* `feat:` means a user-visible feature is being added.
-* `fix:` means a user-visible behavior is being fixed.
-* `refactor:` means some sort of code cleanup that doesn't change user-visible behavior.
+* `feat:` means a user-visible feature is being added. See [Documenting version
+  changes] for how to documenAdd `{versionadded}`
+  to appropriate docs.
+* `fix:` means a user-visible behavior is being fixed. If the fix is changing
+  behavior of a function, add `{versionchanged}` to appropriate docs, as necessary.
+* `refactor:` means some sort of code cleanup that doesn't change user-visible
+  behavior. Add `{versionchanged}` to appropriate docs, as necessary.
 * `revert:` means a prior change is being reverted in some way.
 * `test:` means only tests are being added.
 
 For the full details of types, see
 [Conventional Commits](https://www.conventionalcommits.org/).
 
+### Documenting changes
+
+Changes are documented in two places: CHANGELOG.md and API docs.
+
+CHANGELOG.md contains a brief, human friendly, description. This text is
+intended for easy skimming so that, when people upgrade, they can quickly get a
+sense of what's relevant to them.
+
+API documentation are the doc strings for functions, fields, attributes, etc.
+When user-visible or notable behavior is added, changed, or removed, the
+`{versionadded}`, `{versionchanged}` or `{versionremoved}` directives should be
+used to note the change. When specifying the version, use the values
+`VERSION_NEXT_FEATURE` or `VERSION_NEXT_PATCH` to indicate what sort of
+version increase the change requires.
+
+These directives use Sphinx MyST syntax, e.g.
+
+```
+:::{versionadded} VERSION_NEXT_FEATURE
+The `allow_new_thing` arg was added.
+:::
+
+:::{versionchanged} VERSION_NEXT_PATCH
+Large numbers no longer consume exponential memory.
+:::
+
+:::{versionremoved} VERSION_NEXT_FEATURE
+The `legacy_foo` arg was removed
+:::
+```
+
 ## Generated files
 
 Some checked-in files are generated and need to be updated when a new PR is