From b771223b136dd2f43da20196dfeab943e1f469c7 Mon Sep 17 00:00:00 2001 From: KT Date: Sat, 1 Aug 2026 01:50:05 +0800 Subject: [PATCH 1/2] docs: split the release-notes install by platform and add upgrade 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) --- .github/release-notes-template.md | 32 ++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/.github/release-notes-template.md b/.github/release-notes-template.md index a0cb857c..2fa2dd3f 100644 --- a/.github/release-notes-template.md +++ b/.github/release-notes-template.md @@ -6,16 +6,46 @@ ## Install +New install on Linux, macOS, or WSL2: + ```bash curl -fsSL https://raven.evermind.ai/install.sh | bash ``` -Then reload your shell and run: +New install on native Windows, in PowerShell: + +```powershell +irm https://raven.evermind.ai/install.ps1 | iex +``` + +Windows PowerShell 5.1 (the version built into Windows) rejects that URL with +`Permanent Redirect`; use the direct one instead: + +```powershell +irm https://raw.githubusercontent.com/EverMind-AI/Raven/refs/heads/main/install.ps1 | iex +``` + +Open a new terminal, then run: ```bash raven onboard ``` +## Upgrade + +Already running Raven? Upgrade in place -- configuration, sessions, and memory +are preserved: + +```bash +raven upgrade +``` + +`raven upgrade` installs the latest stable release, so it does not pick up a +pre-release; rerun the installer above for that. Editable source checkouts are +never overwritten -- pull the checkout and rerun its development setup. On +native Windows the upgrade finishes in an external helper; wait for its +completion message before running Raven again. + ## Release Status - Version: `__VERSION__` From b0e80d6b0bc1ec78d257437f28169962d80130ed Mon Sep 17 00:00:00 2001 From: KT Date: Sat, 1 Aug 2026 21:52:19 +0800 Subject: [PATCH 2/2] docs: warn that a draft release URL is temporary, and print both A draft release lives at releases/tag/untagged-, 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) --- .github/workflows/release.yml | 14 ++++++++++++-- RELEASING.md | 16 +++++++++++++++- 2 files changed, 27 insertions(+), 3 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 595dabcd..bd5cf2c3 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -132,10 +132,20 @@ jobs: id="" fi if [ -z "$id" ]; then - gh release create "$tag" dist/*.whl dist/*.tar.gz dist/raven-constraints.txt \ - --title "Raven $ver ($today)" --notes-file "$RUNNER_TEMP/notes.md" --draft $pre + draft_url=$(gh release create "$tag" dist/*.whl dist/*.tar.gz dist/raven-constraints.txt \ + --title "Raven $ver ($today)" --notes-file "$RUNNER_TEMP/notes.md" --draft $pre) + # A draft lives at releases/tag/untagged- and keeps serving that + # stale page after publication, with no redirect to the real tag. Print + # both URLs so nobody shares the draft one by copying the address bar. + { + echo "### Release $tag" + echo "" + echo "- Draft (temporary, do not share): $draft_url" + echo "- Public URL once published: https://github.com/$repo/releases/tag/$tag" + } >> "$GITHUB_STEP_SUMMARY" else echo "Release $tag already published (id=$id); leaving as-is." + echo "Release $tag already published: https://github.com/$repo/releases/tag/$tag" >> "$GITHUB_STEP_SUMMARY" fi # (Optional, wire up when ready) publish to PyPI on tag: diff --git a/RELEASING.md b/RELEASING.md index 87d03e6a..f1900e2d 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -31,9 +31,14 @@ Highlights before publishing. Structure: - ## Install - curl -fsSL https://raven.evermind.ai/install.sh | bash + install.sh one-liner for Linux / macOS / WSL2 + install.ps1 one-liner for native Windows (plus the PowerShell 5.1 direct URL) then: raven onboard +## Upgrade + raven upgrade, with its limits (latest stable only, editable checkouts + untouched, external helper on native Windows) + ## Release Status - Version: `X.Y.Z` - Tag: `vX.Y.Z` @@ -59,6 +64,15 @@ Highlights before publishing. Structure: 4. Fill the summary + Highlights in the draft, then click **Publish**. Publishing makes it `/releases/latest`, which `install.sh` serves. +While a release is a draft, GitHub addresses it as +`releases/tag/untagged-` -- even though the tag already exists, since 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. So never share the draft URL: a reader who opens it after publication +sees "untagged" and concludes the tag is missing or the release never went out. +Link `releases/tag/vX.Y.Z` or `/releases/latest` instead; the release job prints +both URLs in its step summary. + ## Pre-releases - `vX.Y.Z-rcN` tags build a draft marked **pre-release**. A pre-release is never