Bug: release.yml comments point to docs/releasing.md, which does not exist #231

Summary

.github/workflows/release.yml tells readers to "See docs/releasing.md" in two comments, but the repository has no docs/releasing.md, and Git history shows no such file on any branch. Maintainers and contributors who follow the workflow's comments to learn how releases are cut, signed and published find no document. The release workflow itself is unaffected.

Runtime or environment

• main at commit aafd565b99f958ede843a357904ef3819df714da (checked 2026-10-06).
• Latest published release v0.3.1 (tag commit 7a39cb7b89505f7f6f19c83c66d46986d72d4aa9).

Steps to reproduce

1. Clone the repository and check out either build listed under Runtime or environment.
2. Run grep -n "releasing" .github/workflows/release.yml.
3. Run ls -1 docs/ and git log --all --oneline -- docs/releasing.md.

Output on the main build (on v0.3.1 the second match is line 155):

$ grep -n "releasing" .github/workflows/release.yml
2:# creates or updates the draft GitHub Release "VectorCraft v<version>". See docs/releasing.md.
176:    # Debian 12+, Fedora 36+, RHEL 10). See docs/releasing.md.

$ ls -1 docs/
brand
control-protocol.md
development.md
images
mcp.md
plugins.md

$ git log --all --oneline -- docs/releasing.md
(no output)

Expected behavior

A path that a repository file tells readers to "See" exists in the repository, so the comment at the top of release.yml (how the release pipeline works) and the comment on the Linux job (why it runs on the oldest hosted image and which distributions the binaries support) lead to the release documentation they cite.

Actual behavior

On the main build, the references are on lines 2 and 176. On the v0.3.1 build, they are on lines 2 and 155. Neither build contains docs/releasing.md, and a recursive tree listing finds no other path containing "releas" besides .github/workflows/release.yml. git log --all -- docs/releasing.md returns nothing, so the file was never added and then moved or deleted. No open pull request adds it, and ROADMAP.md does not mention planned release documentation.

Evidence

• Expected source: the two "See docs/releasing.md" comments in .github/workflows/release.yml, line 2 and line 176.
• Failure source: the docs/ listing and repository tree on both builds, and git log --all -- docs/releasing.md across all branches, as shown under Steps to reproduce.
• Evidence provenance: observed
• Local verification: reproduced
• Reproduction completeness: complete

Restoration check

Failing: on main, at least one "See docs/releasing.md" reference in .github/workflows/release.yml names a path that does not exist in the repository. Passing: every documentation path that .github/workflows/release.yml tells readers to see exists in the same commit and covers the subject of the comment that cites it.

Additional context

The references arrived with commit da8a14d ("Signed release pipeline"), whose message says it ports PhotoCraft's release workflow. storytold/photocraft has the same two comments and does have a docs/releasing.md, so the comments appear to have been carried over without the document. The same two comments also appear in the release workflows of storytold/filmcraft, storytold/effectcraft, storytold/lightcraft and storytold/printcraft, none of which has docs/releasing.md as of 2026-10-06; the LightCraft and EffectCraft cases are reported in storytold/lightcraft#153 and storytold/effectcraft#136.

Triage assessment

• Impact level: P3
• Assessment status: supported
• Impact basis: The dangling path is in comments only; the release workflow, its jobs and the published artifacts behave the same with or without the file, so the consequence is missing documentation for people reading the workflow, not a behavior change.
• Workaround status: available
• Workaround basis: Readers can learn the release process from the workflow itself and the scripts under packaging/, and PhotoCraft's docs/releasing.md, the source of the ported workflow, describes the same pipeline (release branch, draft release, signing secrets, glibc 2.35 floor), though with PhotoCraft's names and some PhotoCraft-only steps.