From 0d3365e60b164946eca18cc8552c90fe8b0e05eb Mon Sep 17 00:00:00 2001 From: Konstantinos Paparas Date: Thu, 10 Sep 2026 10:31:43 +0200 Subject: [PATCH] docs: give the README what CI actually gates The README listed four commands. CI gates five, and none of the four overlapped with the ones that fail a pull request, so a contributor met check:images or check:anchors for the first time as a red build. - document lint, check:images, check:anchors and check:app-links, each with a line on what it enforces and a pointer to the script header that explains why it exists - document the three branch model. main, develop and bugfixes publish stable, latest and patch simultaneously, and nothing in the repo said so or said which one to target - add prerequisites: node from .nvmrc, pnpm via corepack - say what the repository is and link the published site - split "Build and Preview" in two. preview only serves the last build, so the old heading promised something the command does not do - tag the code fences sh, and point at contribution-guides for the writing conventions --- README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 60 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 1973312..4e81323 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,74 @@ # rotki docs -## Installation +Source for [docs.rotki.com](https://docs.rotki.com): rotki's user guide and contributor +documentation, built with [VitePress](https://vitepress.dev). -``` -pnpm install -``` +## Prerequisites -## Run locally +- Node 24, the version pinned in [`.nvmrc`](.nvmrc) +- pnpm, pinned by `packageManager` in [`package.json`](package.json). Run `corepack enable` + once and the right version is picked up automatically. -``` +## Local development + +```sh +pnpm install pnpm run dev ``` -## Build +`dev` serves the site with hot reload on every save. -``` +To exercise a production build instead: + +```sh pnpm run build +pnpm run preview ``` -## Build and Preview +`preview` only serves what `build` last wrote to disk, so build first or you are previewing a +stale site. +## Checks + +CI runs all of these on every pull request and fails on any of them. Running them locally first +is faster than a round trip through CI: + +```sh +pnpm run lint +pnpm run check:images +pnpm run check:anchors +pnpm run check:app-links ``` -pnpm run preview -``` + +| command | what it enforces | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `lint` | eslint across markdown, TypeScript and Vue sources. `pnpm exec eslint . --fix` clears most of what it reports. | +| `check:images` | Every reference resolves to a real image, every image is referenced by at least one page, and each image sits in the directory mirroring the page that owns it. | +| `check:anchors` | Every internal `#anchor` points at a heading that exists. VitePress verifies the linked page but never the anchor on the end of it, so renaming a heading otherwise breaks links silently. | +| `check:app-links` | The deep links the rotki app makes into these docs still resolve. The app ships with those URLs baked in, so when this fails the fix belongs in the docs, not in the list. | + +Each script in [`scripts/`](scripts) opens with a comment explaining why it exists and what broke +before it did. A pre-commit hook runs eslint over staged files, so most lint problems surface +before you push. + +## Branches and versions + +Three branches are published at once, mirroring the release branches in the main +[rotki](https://github.com/rotki/rotki) repository. A push to any of them rebuilds and redeploys +all three: + +| branch | version | published at | +| ---------- | ------- | -------------------------------- | +| `main` | stable | | +| `develop` | latest | | +| `bugfixes` | patch | | + +Target the branch matching the release your change describes: `main` for the current stable +release, `develop` for what ships in the next minor, `bugfixes` for the next patch. A change that +is true of more than one release has to land on each of those branches separately. See +[releasing.md](contribution-guides/releasing.md) for how the underlying release branches work. + +## Writing the docs + +Page conventions, the contribution workflow and the guides themselves live in +[`contribution-guides/`](contribution-guides/index.md).