## Summary Five sections leave both READMEs: self-hosting, the command reference, the documentation index, the repo layout and the architecture. Each is already a page on the documentation site, and a second copy in the README is the one that drifts. Quick Start now ends by naming the site, so a reader who has just installed Raven is told where the rest lives. English drops 258 lines and Chinese 228, and the two stay in step: every section removed and the pointer added exist in both. The repo-layout table went with them, and it was never only prose. It is the canonical set of commit scopes: a test held it equal to the packages on disk while commitlint computes its enum from that same tree, so the table is what keeps the list a reader is sent to and the list the tooling enforces from splitting. Removing the section broke both of that test's assertions, and the test reads the documentation page now, which carries the same table and the same key directories block. It is renamed with the move, because it no longer reads a README. AGENTS.md, raven/README.md and two comments in commitlint.config.cjs name the page as well. The enum commitlint computes is unchanged at 71 scopes, because it was always read from the tree rather than from the table. Two things are deliberately left alone. The dated records under docs/plans and docs/specs still describe the old location: they record the tree as of their date. And the English README keeps a Showcase section the Chinese one does not have, which is how they already were. ## Type - [ ] Fix - [ ] Feature - [x] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification The coupling was demonstrated rather than assumed: removing the sections first was run against the existing test, which failed with "README.md lost its 'Repo layout' section" and "Key directories lost its agents/ line". After repointing, dropping one table row from the documentation page fails it again with "package on disk without a table row: ['acp']", so the guard still bites from its new source. - `uv run pytest tests/test_scope_canon.py tests/test_docs_site.py tests/test_docker_runtime.py tests/test_living_docs.py tests/test_external_consumer_surface.py` -> 22 passed - `uv run pytest` over the eleven other tests that read a README -> 859 passed - `make lint-python`, `make lint-imports`, `make lint-deps`, `make lint-types` -> exit 0, against an environment synced the way CI installs - `make check-commits`, `make check-source-language`, `make check-large-files`, and `pre-commit run --from-ref origin/main --to-ref HEAD` -> exit 0 - `make docs-build` -> built - `node -e` on commitlint.config.cjs -> 71 scopes, the same set as before - the only internal anchors left in either README are `#readme-top`, whose target is still there, and no remaining link points into a removed section ## Risk User-visible: the README no longer answers self-hosting, the commands, the layout or the architecture; it points at the site instead. Anyone who had bookmarked a README anchor for one of those sections loses it. The scope list AGENTS.md sends a contributor to is now a page rather than a README section. Rollback: revert the commit. Nothing outside the repository depends on the removed sections, and the site pages they moved to were already published. ## Related Issues N/A Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
101 lines
2.6 KiB
JavaScript
101 lines
2.6 KiB
JavaScript
const fs = require("fs");
|
|
const path = require("path");
|
|
|
|
const TYPES = [
|
|
"build",
|
|
"chore",
|
|
"ci",
|
|
"docs",
|
|
"feat",
|
|
"fix",
|
|
"perf",
|
|
"refactor",
|
|
"revert",
|
|
"test",
|
|
];
|
|
|
|
// The canonical scope set mirrors the documentation site's repo-layout
|
|
// table (docs-site/docs/repo-layout.md): every
|
|
// top-level package under raven/ (plus the home.py module), computed from
|
|
// the tree at config-load time so the enum cannot rot behind a refactor.
|
|
function ravenPackages() {
|
|
const root = path.join(__dirname, "raven");
|
|
return fs
|
|
.readdirSync(root, { withFileTypes: true })
|
|
.filter(
|
|
(entry) =>
|
|
entry.isDirectory() &&
|
|
fs.existsSync(path.join(root, entry.name, "__init__.py")),
|
|
)
|
|
.map((entry) => entry.name);
|
|
}
|
|
|
|
// A change living wholly in a top-level tree outside raven/ uses that tree
|
|
// as its scope (see that page's preamble).
|
|
const TOP_LEVEL_TREES = [
|
|
"agents",
|
|
"benchmarks",
|
|
"bridge",
|
|
"docs",
|
|
"evolver",
|
|
"plugins-dist",
|
|
"schemas",
|
|
"scripts",
|
|
"tests",
|
|
"ui-tui",
|
|
"ui-web",
|
|
];
|
|
|
|
// Two files at the repository root rather than a tree, so no directory scan
|
|
// reaches them -- but a change confined to install.sh and install.ps1 is as
|
|
// scoped as one confined to ui-web/, and `*` says less than the truth about it.
|
|
const ROOT_SURFACES = ["installer"];
|
|
|
|
const PRODUCTS = ["raven-code", "raven-design", "raven-oncall", "raven-ppt", "raven-research"];
|
|
|
|
// The plugin distributions beside the host wheel: each is its own package
|
|
// with its own version, so a change confined to one scopes by its wheel name.
|
|
const WHEEL_DISTRIBUTIONS = ["design-engine", "everos-memory", "ppt-engine"];
|
|
|
|
// Scopes already used on refactor/raven_v0_2_0 before the enum existed; a PR
|
|
// from that branch lints its whole history, so they stay legal until the
|
|
// branch merges. Retire this list afterwards.
|
|
const LEGACY_SCOPES = [
|
|
"changelog",
|
|
"context",
|
|
"integration",
|
|
"plans",
|
|
"subagent",
|
|
"subagents",
|
|
"ui",
|
|
"web_rpc",
|
|
];
|
|
|
|
const SCOPES = [
|
|
...new Set([
|
|
...ravenPackages(),
|
|
"home",
|
|
...TOP_LEVEL_TREES,
|
|
...ROOT_SURFACES,
|
|
...PRODUCTS,
|
|
...WHEEL_DISTRIBUTIONS,
|
|
...LEGACY_SCOPES,
|
|
"*",
|
|
"deps",
|
|
"deps-dev",
|
|
]),
|
|
].sort();
|
|
|
|
module.exports = {
|
|
rules: {
|
|
"header-max-length": [2, "always", 100],
|
|
"scope-enum": [2, "always", SCOPES],
|
|
"subject-case": [2, "never", ["sentence-case", "start-case", "pascal-case", "upper-case"]],
|
|
"subject-empty": [2, "never"],
|
|
"subject-full-stop": [2, "never", "."],
|
|
"type-case": [2, "always", "lower-case"],
|
|
"type-empty": [2, "never"],
|
|
"type-enum": [2, "always", TYPES],
|
|
},
|
|
};
|