adamtheturtle · Oct 8, 2026 · Oct 8, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -52,21 +52,12 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      # towncrier writes the rendered notes to stdout (informational
-      # chatter goes to stderr), so this is the curated release body for
-      # this version, not github-tag-action's commit-derived changelog.
-      - name: Generate the GitHub release notes
+      - name: Assemble native Markdown release notes
         env:
           RELEASE: ${{ steps.calver.outputs.release }}
-        run: uv run --group=release towncrier build --draft --version "$RELEASE" >
-          release-notes.md
-
-      # Assemble the same fragments into CHANGELOG.rst under a new
-      # ``$RELEASE`` section and delete the consumed fragment files.
-      - name: Update the changelog
-        env:
-          RELEASE: ${{ steps.calver.outputs.release }}
-        run: uv run --group=release towncrier build --yes --version "$RELEASE"
+        run: |
+          uv run --group=release towncrier build --yes --version "$RELEASE"
+          cp "docs/source/changelog/$RELEASE.md" release-notes.md
 
       - name: Update VERSION file for Nix flake
         env:
@@ -78,7 +69,7 @@ jobs:
         id: commit
         with:
           commit_message: Bump CHANGELOG and VERSION
-          file_pattern: CHANGELOG.rst newsfragments VERSION
+          file_pattern: CHANGELOG.md docs/source/changelog newsfragments VERSION
           # Error if there are no changes.
           skip_dirty_check: true
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,3 @@
+# Changelog
+
+Release notes are stored as [one Markdown file per version](docs/source/changelog/).
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
diff --git a/docs/source/changelog.md b/docs/source/changelog.md
@@ -0,0 +1,11 @@
+# Changelog
+
+Releases are assembled from `newsfragments/` using Towncrier.
+
+```{toctree}
+:maxdepth: 1
+:glob:
+:reversed:
+
+changelog/*
+```
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
diff --git a/docs/source/changelog/2021.10.08.0.md b/docs/source/changelog/2021.10.08.0.md
@@ -0,0 +1,3 @@
+# 2021.10.08.0
+
+Initial release.
diff --git a/docs/source/changelog/2025.03.10.md b/docs/source/changelog/2025.03.10.md
@@ -0,0 +1,3 @@
+# 2025.03.10
+
+- Move documentation to GitHub Pages.
diff --git a/docs/source/changelog/2026.01.22.1.md b/docs/source/changelog/2026.01.22.1.md
@@ -0,0 +1 @@
+# 2026.01.22.1
diff --git a/docs/source/changelog/2026.01.22.2.md b/docs/source/changelog/2026.01.22.2.md
@@ -0,0 +1 @@
+# 2026.01.22.2
diff --git a/docs/source/changelog/2026.01.22.3.md b/docs/source/changelog/2026.01.22.3.md
@@ -0,0 +1 @@
+# 2026.01.22.3
diff --git a/docs/source/changelog/2026.01.22.md b/docs/source/changelog/2026.01.22.md
@@ -0,0 +1 @@
+# 2026.01.22
diff --git a/docs/source/changelog/2026.01.25.1.md b/docs/source/changelog/2026.01.25.1.md
@@ -0,0 +1 @@
+# 2026.01.25.1
diff --git a/docs/source/changelog/2026.01.25.md b/docs/source/changelog/2026.01.25.md
@@ -0,0 +1 @@
+# 2026.01.25
diff --git a/docs/source/changelog/2026.02.07.1.md b/docs/source/changelog/2026.02.07.1.md
@@ -0,0 +1 @@
+# 2026.02.07.1
diff --git a/docs/source/changelog/2026.02.07.2.md b/docs/source/changelog/2026.02.07.2.md
@@ -0,0 +1 @@
+# 2026.02.07.2
diff --git a/docs/source/changelog/2026.02.07.md b/docs/source/changelog/2026.02.07.md
@@ -0,0 +1,3 @@
+# 2026.02.07
+
+- Add support for installing with winget on Windows.
diff --git a/docs/source/changelog/2026.02.15.1.md b/docs/source/changelog/2026.02.15.1.md
@@ -0,0 +1 @@
+# 2026.02.15.1
diff --git a/docs/source/changelog/2026.02.15.2.md b/docs/source/changelog/2026.02.15.2.md
@@ -0,0 +1 @@
+# 2026.02.15.2
diff --git a/docs/source/changelog/2026.02.15.md b/docs/source/changelog/2026.02.15.md
@@ -0,0 +1 @@
+# 2026.02.15
diff --git a/docs/source/changelog/2026.02.22.md b/docs/source/changelog/2026.02.22.md
@@ -0,0 +1 @@
+# 2026.02.22
diff --git a/docs/source/changelog/2026.08.16.1.md b/docs/source/changelog/2026.08.16.1.md
@@ -0,0 +1,3 @@
+# 2026.08.16.1
+
+No documented changes.
diff --git a/docs/source/changelog/2026.08.16.md b/docs/source/changelog/2026.08.16.md
@@ -0,0 +1,5 @@
+# 2026.08.16
+
+- Drop Python 3.13 support, and update VWS Python so that the documented `ProjectHasNoApiAccess` result code spelling gives a friendly error message.
+- Add Model Target dataset commands: `vws create-model-target-dataset`, `vws get-model-target-dataset-status`, `vws wait-for-model-target-dataset-generated`, `vws download-model-target-dataset` and `vws delete-model-target-dataset`.
+- Add a `vws get-database-reco-counts-report` command, which requests a per-target recognition counts report for a month, waits for Vuforia to generate it, and writes the CSV to stdout or to a path.
diff --git a/docs/source/changelog/2026.08.30.1.md b/docs/source/changelog/2026.08.30.1.md
@@ -0,0 +1,3 @@
+# 2026.08.30.1
+
+No documented changes.
diff --git a/docs/source/changelog/2026.08.30.2.md b/docs/source/changelog/2026.08.30.2.md
@@ -0,0 +1,3 @@
+# 2026.08.30.2
+
+No documented changes.
diff --git a/docs/source/changelog/2026.08.30.3.md b/docs/source/changelog/2026.08.30.3.md
@@ -0,0 +1,3 @@
+# 2026.08.30.3
+
+No documented changes.
diff --git a/docs/source/changelog/2026.08.30.4.md b/docs/source/changelog/2026.08.30.4.md
@@ -0,0 +1,3 @@
+# 2026.08.30.4
+
+No documented changes.
diff --git a/docs/source/changelog/2026.08.30.5.md b/docs/source/changelog/2026.08.30.5.md
@@ -0,0 +1,3 @@
+# 2026.08.30.5
+
+No documented changes.
diff --git a/docs/source/changelog/2026.08.30.md b/docs/source/changelog/2026.08.30.md
@@ -0,0 +1,5 @@
+# 2026.08.30
+
+- Handle all VWS and Cloud Reco service errors with clear CLI messages, and use consistent messages for target status and polling timeout errors.
+- Test Model Target authentication, client, rate-limit, and server failures through public CLI commands and the configurable mock.
+- Update vws-python and vws-python-mock to their releases containing configurable Model Target failure coverage.
diff --git a/docs/source/changelog/2026.09.08.md b/docs/source/changelog/2026.09.08.md
@@ -0,0 +1,3 @@
+# 2026.09.08
+
+- Check that Gatekeeper accepts the signed and notarized macOS binaries during the release, and remove the quarantine workaround from the install docs.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -20,6 +20,7 @@
 author = _pyproject_config.author
 
 extensions = [
+    "myst_parser",
     "sphinx_copybutton",
     "sphinxcontrib.spelling",
     "sphinxcontrib.towncrier.ext",
@@ -29,15 +30,15 @@
 ]
 
 # Render the unreleased ``newsfragments/`` entries into
-# ``docs/source/unreleased.rst`` so the Sphinx spelling, doc-build and
+# ``docs/source/unreleased.md`` so the Sphinx spelling, doc-build and
 # link-checking gates cover the prose before it is assembled into
-# CHANGELOG.rst at release time.
+# the versioned Markdown notes at release time.
 towncrier_draft_autoversion_mode = "draft"
 towncrier_draft_include_empty = True
 towncrier_draft_working_directory = f"{_pyproject_file.parent}"
 
 templates_path = ["_templates"]
-source_suffix = ".rst"
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
 master_doc = "index"
 
 project_copyright = f"%Y, {author}"

diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -77,3 +77,10 @@ Performing a release
 --------------------
 
 See :doc:`release-process`.
+
+Release notes
+-------------
+
+Write user-facing changes as Markdown in ``newsfragments/<issue>.change.md``.
+Towncrier writes one Markdown file per version, used directly for GitHub release notes.
+Invalid fragment names fail release assembly.
diff --git a/docs/source/unreleased.md b/docs/source/unreleased.md
@@ -0,0 +1,7 @@
+# Unreleased changes
+
+Changes merged into the main branch but not yet part of a tagged release.
+These entries are assembled into the {doc}`changelog` when the next release is published.
+
+```{towncrier-draft-entries}
+```
diff --git a/docs/source/unreleased.rst b/docs/source/unreleased.rst
diff --git a/docs/towncrier_template.rst.jinja b/docs/towncrier_template.rst.jinja
diff --git a/newsfragments/+native-markdown.change.md b/newsfragments/+native-markdown.change.md
@@ -0,0 +1 @@
+Publish native Markdown release notes and use the same notes in documentation where available.
diff --git a/newsfragments/2588.change.rst → newsfragments/2588.change.md b/newsfragments/2588.change.rst → newsfragments/2588.change.md
diff --git a/newsfragments/2589.change.rst → newsfragments/2589.change.md b/newsfragments/2589.change.rst → newsfragments/2589.change.md
diff --git a/newsfragments/2596.change.rst → newsfragments/2596.change.md b/newsfragments/2596.change.rst → newsfragments/2596.change.md
diff --git a/newsfragments/README.md b/newsfragments/README.md
@@ -0,0 +1,10 @@
+# Release notes
+
+Add user-facing changes in `newsfragments/<issue>.<type>.md`, using an issue or pull request number.
+The available types are `change`.
+Use `+name.<type>.md` for changes without an issue number.
+
+Write GitHub-compatible Markdown, including inline code, explicit links, and lists.
+Towncrier writes one Markdown file per version and rejects invalid fragment names.
+GitHub publishes that file directly as the release description.
+Sphinx uses MyST to read the same release notes.
diff --git a/prek.toml b/prek.toml
@@ -453,7 +453,7 @@ hooks = [
     name = "linkcheck",
     entry = "uv run --group=dev sphinx-build -M linkcheck docs/source docs/build -W",
     language = "python",
-    types_or = ["rst"],
+    types_or = ["rst", "markdown"],
     stages = ["manual"],
     pass_filenames = false,
     additional_dependencies = ["uv==0.11.7"]
@@ -463,7 +463,7 @@ hooks = [
     name = "spelling",
     entry = "uv run --group=dev sphinx-build -M spelling docs/source docs/build -W",
     language = "python",
-    types_or = ["rst"],
+    types_or = ["rst", "markdown"],
     stages = ["manual"],
     pass_filenames = false,
     additional_dependencies = ["uv==0.11.7"]
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Changelog

		Release notes are stored as [one Markdown file per version](docs/source/changelog/).
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# 2025.03.10

		- Move documentation to GitHub Pages.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# 2026.02.07

		- Add support for installing with winget on Windows.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# 2026.09.08

		- Check that Gatekeeper accepts the signed and notarized macOS binaries during the release, and remove the quarantine workaround from the install docs.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Publish native Markdown release notes and use the same notes in documentation where available.