Repository navigation
docs: docs index, install chooser, style guide and link check (PR 3 of REORG-PLAN) - #491
Conversation
- docs/index.md: documentation map and maturity legend. - docs/get-started/index.md: mocactl install and a backend chooser with labels, prerequisites summary and a list of what is not supported yet. - docs/CONTRIBUTING-DOCS.md: placement rules, standard banners, page conventions, terminology and link rules. - scripts/check-doc-links.py, make check-links and a CI docs job: offline check of relative links and in-repo anchors. - PR template with a docs checklist; CONTRIBUTING.md points to the style guide. - REORG-PLAN: record what PR 3 shipped and deferred. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
The PR 3 row edit had also replaced the deprecation conventions row 3 (Never deprecate in favour of something less stable). Restore it. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
ingpaolodettori-dev
left a comment
ingpaolodettori-dev
left a comment
There was a problem hiding this comment.
Docs skeleton and tooling for PR 3 of REORG-PLAN. It adds docs/index.md, the get-started/ chooser, CONTRIBUTING-DOCS.md, an offline link and anchor checker with a docs CI job, and a PR template. Nothing existing is moved.
I checked the new pages against the repo at 891fd24:
- Every link in the new pages resolves. That includes
migrating-from-knative.md#if-you-depend-on-async-fan-out-or-the-cronjob, and the CIdocsjob is green on the whole tree. - The chooser's prerequisites trace to their sources: installer (Node 22,
~/.local/bin,MOCACTL_*), Compose README (no root, trial path), VM README (systemd 247+, netavarkisolate=strict,nft, AL2023), k8s README (kind 0.24+), REORG-PLAN audit (OpenShift 4.20.8), P4-ON-P6 (/dev/kvm, cgroups v2, no swap,--remote). docs/plans/is gitignored as the style guide says.- The new CI job uses the repo's pinned
actions/checkoutSHA under the workflow's top-levelcontents: read. - The second commit only restores the conventions-table row. The REORG-PLAN diff is now limited to the PR table.
Nothing blocking. The inline comments are one suggestion (label vs registry, under the PR's own new rule) and a few nits.
Author: pdettori (MEMBER, maintainer). No .claude//.vscode/ changes. 2 commits, both signed off. CI: 14/14 green.
| | Try MOCA in about five minutes, no root | [Docker Compose](../../deploy/compose/README.md) | Preview | Docker (or podman's `docker` CLI) with Compose, `curl`, a model credential. A trial, not production. | | ||
| | Run it for real on one machine | [Single VM](../../deploy/vm/README.md) | Preview | A Linux VM with systemd 247+, podman (netavark `isolate=strict`), `nft`, Node 22+. Verified on Amazon Linux 2023. | | ||
| | Run it on a cluster (Kind or OpenShift) | [P6 on Kubernetes](../../deploy/k8s/README.md) | Preview | A NetworkPolicy-enforcing CNI (Kind 0.24+); accepted on OpenShift 4.20.8. | | ||
| | Add per-`Exec` Firecracker microVM sandboxes | [P4 microVM tier](../../deploy/microvm/P4-ON-P6.md) | Preview | A KVM host (`/dev/kvm`, cgroups v2, no swap, Firecracker and jailer), attached to a P6 VM host or, with `--remote`, to the in-cluster relay. See the limits section of that page. | |
There was a problem hiding this comment.
suggestion: This row labels P4 Preview, which docs/index.md defines as "implemented". The milestone registry (docs/specs/README.md, P4 row) still says design ✅ (infra gate retired), while P6.2, which attaches external P4 hosts, is implemented. CONTRIBUTING-DOCS.md:26 (added in this PR) says the label must agree with the registry, and that a mismatch is fixed in the registry in the same change. Please flip P4's registry status to implemented (or whatever is accurate), or say here why it stays Preview while the registry says design.
| | I want to... | Path | Label | You need | | ||
| | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | Try MOCA in about five minutes, no root | [Docker Compose](../../deploy/compose/README.md) | Preview | Docker (or podman's `docker` CLI) with Compose, `curl`, a model credential. A trial, not production. | | ||
| | Run it for real on one machine | [Single VM](../../deploy/vm/README.md) | Preview | A Linux VM with systemd 247+, podman (netavark `isolate=strict`), `nft`, Node 22+. Verified on Amazon Linux 2023. | |
There was a problem hiding this comment.
nit: The "you need" summary for Single VM leaves out three things deploy/vm/README.md lists: pnpm 9+, a built workspace (the units run node --import tsx), and root to install the systemd units. The column is marked as a summary, but pnpm and root are the items most likely to surprise someone choosing between Compose and VM.
| curl -fsSL https://raw.githubusercontent.com/rossoctl/moca/main/scripts/install-mocactl.sh | sh | ||
| ``` | ||
|
|
||
| It needs Node 22+ and installs to `~/.local/bin`. `MOCACTL_VERSION` (`edge` or `vX.Y.Z`) and |
There was a problem hiding this comment.
nit: MOCACTL_VERSION also accepts latest, which is the default (scripts/install-mocactl.sh:21). "(latest, edge or vX.Y.Z)" would match the installer's own error message.
| ALLOW = {("SECURITY.md", "../../security/advisories/new")} | ||
|
|
||
| LINK = re.compile(r"\[(?:[^\]\\]|\\.)*\]\(\s*<?([^)\s>]+)>?(?:\s+\"[^\"]*\")?\s*\)") | ||
| FENCE = re.compile(r"^(```|~~~).*?^\1", re.S | re.M) |
There was a problem hiding this comment.
nit: FENCE only strips fences that start in column 0. Indented fences inside list items appear in 11 tracked Markdown files (for example deploy/vm/README.md, deploy/k8s/README.md), so their contents are scanned as prose: links in them are checked, and # comment lines in a bash block would register as heading anchors. Reference-style links ([x]: path, e.g. docs/demos/promoted-workflow-demo.md:656) aren't checked at all. Neither causes a failure today. Allowing leading whitespace (^[ \t]*(```|~~~).*?^[ \t]*\1) and adding a pattern for ^\s*\[[^]]+\]:\s*(\S+) would close both.
| ```markdown | ||
| > **Deprecated 2026-10-11 ([ADR-0041](<relative path>/adrs/0041-deprecate-knative-keda-deployment.md)).** | ||
| > <What this page describes> is deprecated: security and breakage fixes only, and removal comes no | ||
| > earlier than **end of October 2026**, once the remaining users have migrated. P6 is the primary |
There was a problem hiding this comment.
nit: The Legacy template is said to match the existing deploy/knative/ banners, but it drops their "P6 — the process-manager runtime — is the primary…" gloss. The Terminology section of this page (line 70) asks for that gloss on first use of P6 in a page. Keep it in the template so new banners don't introduce a bare "P6".
| @@ -0,0 +1,12 @@ | |||
| ## What and why | |||
There was a problem hiding this comment.
nit: Consider ## Summary instead of ## What and why. It's the section name the review conventions look for, and what most PR bodies here already use. The hint comment can keep "what and why".
- Registry: P4 is implemented (verified 2026-09-30, limits listed), so the Preview label matches the registry. - Chooser: add pnpm 9+, the built workspace and root to the single-VM prerequisites; document MOCACTL_VERSION=latest. - Link checker: skip indented fences and check reference-style links. - Legacy banner template keeps the P6 gloss; PR template uses Summary. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
|
Addressed in 383bcb2: P4 registry row flipped to implemented (verified run 2026-09-30, limits linked; ADR-0035 is still Proposed per the earlier decision), VM prerequisites and |
2 participants
Docs skeleton and tooling (PR 3 of docs/REORG-PLAN.md)
Adds the entry points and guardrails the plan calls for, without moving or rewriting any existing doc. #488 and #489 are merged; this is based on current
main.Added
docs/index.md: a map ofdocs/and the Stable / Preview / Legacy maturity legend. It links only to files that exist.docs/get-started/index.md:mocactlinstall and a backend chooser (Compose, single VM, P6 on Kubernetes, P4 microVM, and the Legacy Knative guides) with a label and a prerequisites summary for each, plus a "not supported yet" list: P4 inside a cluster, P4/P6 on macOS or Windows, async and cron on P6.docs/CONTRIBUTING-DOCS.md: where content goes, the standard Legacy and Preview banners (the Legacy one matches the wording already ondeploy/knative/), page conventions, terminology, link rules.CONTRIBUTING.mdlinks to it.scripts/check-doc-links.py,make check-links, CI jobdocs: offline check of relative links and in-repo anchors over tracked Markdown (stdlib Python, no new action to pin). It passes on the whole tree today (155 files) and I confirmed it fails on a missing target and a missing anchor..github/PULL_REQUEST_TEMPLATE.md: DCO, lint, docs and registry checklist.docs/REORG-PLAN.md: the PR 3 row now records what shipped and what is deferred.Deferred on purpose
mkdocs.yml/ a site: hosting is still an open question (Q12), and much of the documentation links outsidedocs/(for example../deploy/...), which MkDocs would flag as broken. Worth deciding before building one.*rule already coversdocs/; who owns docs is Q10.Please check
Verification
python3 scripts/check-doc-links.pyreports 0 broken links; Prettier run on the changed files; CI YAML parses.make lintnot run here (nonode_modulesin this worktree).Assisted-By: Claude (Anthropic AI) noreply@anthropic.com