Skip to content

docs: split release install by platform, warn on draft links - #262

Open
0xKT wants to merge 2 commits into
mainfrom
docs/release_notes_template_install
Open

docs: split release install by platform, warn on draft links#262
0xKT wants to merge 2 commits into
mainfrom
docs/release_notes_template_install

Conversation

@0xKT

@0xKT 0xKT commented Jul 31, 2026

Copy link
Copy Markdown
Contributor

Summary

Two fixes to how a release is presented, both found while cutting 0.1.10.

Install / Upgrade in the release notes. The template shipped a single
curl | bash line, so every release page told native Windows readers nothing
about install.ps1 and told existing users nothing about upgrading -- even
though a release page is mostly read by people who already run Raven. Install
now has one block per platform, mirroring README: install.sh for
Linux / macOS / WSL2, install.ps1 for native Windows plus the PowerShell 5.1
direct-URL note (the short URL fails there with Permanent Redirect). A new
Upgrade section gives raven upgrade and its three limits: latest stable only,
so a pre-release still needs the installer (rc tags are published with
--prerelease and never become /releases/latest); editable checkouts are
never overwritten; on native Windows an external helper finishes the job.

The draft-link trap. GitHub addresses a draft release as
releases/tag/untagged-<hash>, even when the tag already exists -- CI only runs
after the tag is pushed. Publishing moves the release to releases/tag/vX.Y.Z
and leaves the old URL serving its own stale page with no redirect. With 0.1.10
that draft link had been shared, so after publication two readers hit the stale
page and concluded, once that the tag was never pushed and once that publishing
had not taken effect; both were wrong. RELEASING.md now states this at the
publish step, and the release job prints the draft URL next to the public one in
its step summary, so whoever cuts the release has the correct link at hand
instead of copying the address bar. The notes skeleton in RELEASING.md is also
brought in line with the new template.

Type

  • Fix
  • Feature
  • Docs
  • CI / tooling
  • Refactor
  • Other

Verification

  • sed "s/__VERSION__/0.1.11/g; s/__TAG__/v0.1.11/g" .github/release-notes-template.md
    -> both placeholders substituted, no leftover __ markers

  • Applied the same Install / Upgrade section to the pending 0.1.10 draft release
    and reviewed the rendered GitHub page before committing; that draft's summary,
    Highlights, Release Status, and Notes were left untouched

  • release.yml parsed with yaml.safe_load, and the modified run: block
    checked with bash -n

  • Every CI check reproduced locally, all green: npx commitlint --from origin/main --to HEAD --config commitlint.config.cjs,
    uv run --extra dev python scripts/check_commit_messages.py origin/main..HEAD,
    uv run --extra dev python scripts/check_large_files.py origin/main..HEAD,
    uv run pre-commit run --from-ref origin/main --to-ref HEAD, make lint-python,
    make test-python (5143 passed, 30 skipped), plus
    scripts/check_pr_title.py and scripts/check_pr_body.py on this title and body

  • Relevant tests pass locally

  • Relevant lint / type checks pass locally

  • User-facing docs or screenshots are updated when needed

Risk

Documentation, plus one added step-summary write in the release workflow. No
runtime code path changes; already-published release notes are unaffected. The
workflow change only adds output -- the release-creation logic is untouched, and
the else branch (release already published) keeps its existing behaviour.
Rollback is reverting the two commits.

  • Security impact considered
  • Backward compatibility considered
  • Rollback path is clear for risky changes

Related Issues

N/A

0xKT and others added 2 commits August 1, 2026 01:50
The release-notes template offered only the Linux/macOS curl one-liner, so
native Windows readers had no install path and existing users had no upgrade
command -- yet a release page is read mostly by people who already run Raven.

Mirror what README already documents: install.sh for Linux/macOS/WSL2,
install.ps1 for native Windows (with the PowerShell 5.1 direct-URL note), plus
a raven upgrade section carrying its three limits -- latest stable only (so a
pre-release needs the installer), editable checkouts never overwritten, and the
external helper that finishes the upgrade on native Windows.

Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
A draft release lives at releases/tag/untagged-<hash>, and publishing leaves
that URL serving its own stale page with no redirect to releases/tag/vX.Y.Z.
A draft link shared with anyone therefore reads later as "the tag is missing"
or "the release never went out" -- which is how 0.1.10 was read twice.

RELEASING.md now says this at the publish step, and the release job prints the
draft URL next to the public one in its step summary, so whoever cuts the
release has the right link without copying the address bar. The notes skeleton
in RELEASING.md also picks up the Install / Upgrade split this branch made to
the template.

Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
@0xKT 0xKT changed the title docs: split the release-notes install by platform, add upgrade docs: split release install by platform, warn on draft links Aug 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant