Repository navigation
docs: add an Update Raven section to the quick start - #711
Conversation
The README says how to install Raven and not how to update it. The two
answers differ by how Raven was installed, and the obvious one is wrong
for a source checkout: `raven upgrade` refuses an editable install
("Pull the source checkout and rebuild Raven").
A release install updates by running its one-line installer again, or
with `raven upgrade` between `raven web --stop` and `raven web`: the
CLI's upgrade hands the install to a helper that relaunches nothing, and
the page's own update refuses when the page is hosted by `raven gateway`,
which is what `raven web` runs. A source checkout updates with `git
pull` and the installer run as a file again, which rebuilds the TUI
bundle and the served page only when their sources are newer and starts
the WebUI again in the foreground. The zh README says the same.
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
gloryfromca
left a comment
gloryfromca
left a comment
There was a problem hiding this comment.
No blockers; this can merge as far as I am concerned.
I reviewed the full README diff and its surrounding install guidance, then cross-checked the documented release and source-update paths against raven upgrade, both installers, their focused tests, and the relevant history. The English and Chinese instructions agree, the claims about editable installs, conditional frontend rebuilds, WebUI stop/start behavior, and persisted Raven-home data are consistent with the implementation.
Coverage: I checked the repository rules in AGENTS.md/CLAUDE.md and the terminology routing in CONTEXT-MAP.md; the diff itself and surrounding documentation; the affected command/installer behavior and history; backward compatibility; test integrity (no tests were changed or weakened); and the applicable architecture boundary (documentation only, with no runtime dependency or RPC change). There are no code callers introduced by this documentation-only change.
Verification: uv run pytest tests/test_install_script.py tests/test_updates_upgrade.py -x passed (170 tests); git diff --check github/main...HEAD passed; the large-file and source-language checks passed when their underlying Python commands were run directly. make check-large-files itself could not be invoked because make is unavailable in this environment. The PR's docs-build, installer, upgrade, lint, and repository-file checks visible at review time were also green.
…EADME The update steps belong beside the install steps on the documentation site's quick start page, not in the README, so the README change is reverted and the quick start gains an Update Raven section after Install Raven, in English and Chinese. It has two subsections, one per way Raven was installed. A one-line install updates by running its installer again, or with `raven upgrade` between `raven web --stop` and `raven web`, since the CLI's upgrade relaunches nothing and the page's own update refuses under `raven gateway`. A source checkout updates with `git pull` and the installer run as a file again; `raven upgrade` refuses an editable install. The subsections are named so their anchors do not collide with Install's "From a source checkout", and the zh page carries the same anchors. Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
Handsome-wzw
changed the title
gloryfromca
left a comment
gloryfromca
left a comment
There was a problem hiding this comment.
No blockers; this can merge as far as I am concerned.
I reviewed the delta from the previously reviewed revision and the resulting full diff. Moving the update guidance from the READMEs to the bilingual quick-start pages is coherent with the site structure, and the generated English anchors match the explicit Chinese anchors. The referenced runtime and installer interfaces are unchanged, and this revision changes no tests or compatibility surface.
Coverage for this revision: repository rules in AGENTS.md/CLAUDE.md and CONTEXT-MAP.md, the full diff and surrounding quick-start pages, the unchanged referenced command/installer behavior and relevant history, backward compatibility, test integrity, and the documentation-only architecture scope.
Verification: the strict MkDocs build passed locally for both languages; the large-file and source-language checks passed; git diff --check github/main...HEAD passed. The docs build also passed in CI at review time.
## Summary Both READMEs now open Quick Start with a short subsection for readers who would rather have their own agent install Raven. It holds one prompt to paste into any agent that can read a web page and run shell commands. The prompt sends the agent to the quick start page on the documentation site and asks it to install Raven, or to update it when it is already installed. The page covers both paths since its Update Raven section landed in #711, so this route adds no install steps to the README that could drift from the page. The prompt sits in a fenced `text` block, which GitHub renders with a copy button, so one click copies the whole prompt. It stays on a single line so that pasting it cannot send half a prompt in an agent whose input submits on a newline. The Chinese README points at the Chinese page, as its documentation link already does. Known gap, left to the page: an install that an agent runs by following the page ends on the WebUI in the foreground and does not return until it is stopped. The page's Update Raven section says a re-run of the installer finishes that way; the Install Raven section does not say the first install does the same, and neither names `RAVEN_NO_LAUNCH=1`, the setting that makes the installer return. That belongs to a separate docs-site change. ## Type - [ ] Fix - [ ] Feature - [x] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification Every command ran against this branch's tree, with the project venv's Python. - `python -m pytest tests/test_cli_onboard_commands.py::test_readme_quickstart_matches_the_installer -q -o addopts=""` -> `1 passed`. This is the test that reads the Quick Start section of both READMEs. - `python scripts/check_commit_messages.py origin/main..HEAD` -> exit 0. - `commitlint --from origin/main --to HEAD --config commitlint.config.cjs` -> `found 0 problems, 0 warnings`. - `python scripts/check_large_files.py origin/main...HEAD` and `python scripts/check_source_language.py origin/main...HEAD` -> exit 0 each. - `pre-commit run --from-ref origin/main --to-ref HEAD` -> trailing whitespace, end of files, large files, merge conflicts and private key passed; every other hook had no files to check. - Copy button, checked in headless Chromium at 1440x900 on this branch's blob view of both READMEs: the block carries GitHub's `clipboard-copy` button, the button shows on hover, and one click puts exactly the committed prompt on the clipboard (129 characters in README.md, 91 in README.zh-CN.md, no newline). The clipboard held a different string before the click, so a click that copied nothing would have failed. - Both pages the prompts name return 200 and carry the Update Raven section: https://evermind-ai.github.io/Raven/quick-start/ and https://evermind-ai.github.io/Raven/zh/quick-start/ - The `#-quick-start` and `#-install` anchors are unchanged; the new heading adds `#-install-with-your-agent`. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed ## Risk User-visible change: one new subsection at the top of Quick Start in both READMEs; nothing else in either file moves. The prompt asks an agent to read the project's documentation page and run the installer that page names, which is the same trust the README's own `curl ... | bash` line already asks of a reader. No existing anchor or link changes. Rollback is reverting this commit. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes ## Related Issues N/A Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
3 participants
Summary
The quick start page on the documentation site says how to install Raven and
not how to update it. The two answers differ by how Raven was installed, and the
command a reader reaches for first is wrong for a source checkout:
raven upgraderefuses an editable install with "Editable Raven installations cannotbe upgraded automatically. Pull the source checkout and rebuild Raven."
This adds an Update Raven section after Install Raven on the quick start
page, in English and Chinese, with one subsection per way Raven was installed.
The README is unchanged.
raven upgradebetweenraven web --stopandraven web. The stop and start areneeded because the CLI's upgrade hands the install to a helper that relaunches
nothing (
raven/updates/upgrade.py: "The CLI passes 4 args and keeps the oldexec-in-place behaviour"). The one path that does relaunch is the served
page's own update, and it refuses when the page is hosted by
raven gateway(
system.upgrade: "Runraven upgrade, then restart the gateway"), which iswhat
raven webruns.git pull, then the installer run as a fileagain (
./install.sh, or.\install.ps1in PowerShell). Both scriptsreinstall the checkout in editable mode, rebuild the TUI and WebUI only when a
source file is newer than the built one (
is_staleininstall.sh, theLastWriteTimeUtccheck ininstall.ps1), stop a running WebUI, and end inraven web --foreground.WebUI that Ctrl-C stops and
raven webrestarts in the background, and thesettings and conversations in
~/.ravenuntouched -- neither script writesthere beyond the Node runtime.
The subsections are named "Update a one-line install" and "Update a source
checkout" rather than reusing Install's "From a source checkout", whose anchor a
second heading of that name would collide with. The zh page gives each heading
the same explicit anchor the English page generates.
Type
Verification
Every sentence was checked against the code it describes, not against earlier
docs:
raven/cli/upgrade_commands.py(the editable refusal),raven/updates/upgrade.py(the helper's relaunch argument and the CLI's four-argument handoff),
raven/rpc/methods/system.py(system.upgraderefusing underraven gateway),and the closing steps and staleness checks of
install.shandinstall.ps1.raven upgrade --helplists--checkas described. On this machine a re-run of./install.shfrom a checkout stopped the running WebUI, skipped the page buildbecause the page was newer than its sources, and ended in
raven web --foreground.uv run --frozen --python 3.12 --only-group docs mkdocs build -f docs-site/mkdocs.yml --strict-- exit 0, no warnings
In the built site, the English page's generated anchors and the zh page's
explicit ones are the same (
update-raven,update-a-one-line-install,update-a-source-checkout), and both pages list the three headings in theirtable of contents
scripts/check_source_language.py,scripts/check_commit_messages.py,scripts/check_pr_title.py-- all cleanRelevant tests pass locally
Relevant lint / type checks pass locally
User-facing docs or screenshots are updated when needed
Risk
Docs only; no behaviour changes. The section describes two facts that live in
code and could drift from it: that
raven upgradedoes not restart a runningWebUI, and that both installers end in a foreground
raven web. If eitherchanges, this section should change with it. Rollback is a revert.
Related Issues
N/A