Developer Resources

Review Lanes

Every change to documentation follows one of five review lanes. Changes that touch nothing under docs/ carry no lane at all — see Changes with no review lane at the end of this chapter.

Whether a pull request gets a lane is decided by content, not by branch name: a PR that changes at least one file under docs/ is a documentation PR. For those, the workflow assigns a lane automatically using two signals, in order:

1. Content-based detection. If every documentation file changed in the PR is under docs/dev/, the PR is assigned lane:dev regardless of branch name.
2. Administrator classification. The branch prefix suggests intent, but an administrator records or corrects the authoritative classification with /review classify.

Branch prefix	Lane
docs/new/	New document (Lane 1)
docs/major/	Major revision (Lane 2)
docs/minor/	Minor revision (Lane 3)
docs/fix/	Editorial fix (Lane 4)
docs/dev/	Dev docs (Lane 5)

Any PR that touches files under docs/ is processed by the review workflow, even if its branch name does not start with docs/. A documentation change accidentally pushed on a branch named feature/typo-fix is still intercepted at PR open time, and a site administrator is asked to assign a lane.

If a branch starts with docs/ but does not match one of the five sub-prefixes above — for example, a typo like docs/newfoo/ or an old-style name like docs/update — the workflow applies stage:needs-lane and tags a site administrator to assign the correct lane manually. The same happens for a PR that touches documentation from a non-docs/ branch when content-based dev detection does not apply.

A site administrator can always override the automatically-detected lane by swapping the lane:* label on the PR. The workflow treats a manually-applied lane label the same as an auto-detected one and proceeds normally from there.

Lane 1: New document

When to use. Any completely new document being added to the site.

Required reviews. Content PR: Peer review → RMC Lead Civil review → Technical edit. Separate Director review follows draft publication.

What happens. Peer review, Lead Civil review, and the manually initiated technical edit occur in the Content PR. An administrator records technical completion, then merges the PR to main, which automatically deploys the document as a draft. A separate full-document Director Review PR follows. Approval or waiver creates a Publication PR that removes the watermark after administrator merge and production approval.

Example branches: docs/new/totalrisk-applications-guide, docs/new/lifesim-validation-oroville

Lane 2: Major revision

When to use. Substantial changes to an existing document warranting a new major version (e.g., v1.0 → v2.0).

Required reviews. Peer review → RMC Lead Civil review → Technical edit (AI-assisted).

What happens. The entire review happens on the preview URL. The old version stays live and unwatermarked. After the technical edit comments are addressed, the site administrator flips the draft flag, merges, and deploys. The new version becomes the default; the old version remains accessible via direct URL.

Example branches: docs/major/bep-progression-v2.0

Lane 3: Minor revision

When to use. Smaller updates warranting a minor version bump (e.g., v1.0 → v1.1).

Required reviews. Peer review → Technical edit (AI-assisted).

What happens. Same as Lane 2 but without Lead Civil review.

Example branches: docs/minor/bep-progression-v1.1

Lane 4: Editorial fix

When to use. Typos, broken links, grammatical corrections that do not change technical meaning.

Required reviews. None. The site administrator reviews and merges directly.

No version change, no watermark.

Example branches: docs/fix/bep-progression-typos

Lane 5: Dev docs

When to use. Any new or revised document under docs/dev/ — developer documentation, contributor guides, internal references, planning documents, and similar materials.

Required reviews. None. The site administrator reviews and merges directly, same as Lane 4.

Classification. Use a descriptive docs/dev/ prefix. An administrator records /review classify dev <doc_location>; content detection may inform the suggestion but does not replace that action.

No version change, no watermark.

Example branches: docs/dev/ai-development-guide, feature/update-contributor-guide (content detected under docs/dev/)

Changes with no review lane

Not every change to this repository is a documentation change. React components, CSS, build scripts, Docusaurus configuration, and GitHub workflows all live in the same repository, and none of them carry the review machinery described above.

The deciding factor is content, not branch name. A pull request that changes at least one file under docs/ is a documentation PR and is assigned a lane. A pull request that changes nothing under docs/ gets no lane:* label, no stage:* label, and no review stages.

Branch prefixes for non-documentation work

Branch prefix	Use for
feature/	New components, new site capabilities, enhancements
fix/	Bug fixes in components, styles, scripts, or build tooling
chore/	Dependency bumps, refactors, configuration, cleanup
ci/	GitHub workflows and repository automation

These prefixes are a readability convention — nothing in the workflow parses them, and no automation will reject a branch named otherwise. They exist so that a glance at the branch list separates content work from code work. Some older branches in this repository use enhancement/; use feature/ for new work.

Example branches: feature/video-component, fix/hardcoded-baseurl-paths, chore/bump-docusaurus, ci/pr-preview-cleanup

The review process, in full

There is none. That is the entire point of this section, and it is worth stating explicitly because the five lanes above can give the impression that everything here is reviewed.

1. Open the pull request. The lane workflow inspects the changed files, finds nothing under docs/, and stops. No lane label, no stage label, no bot commentary about reviewers.
2. CI Build runs npm run build against the branch. This is the only gate that matters.
3. When the build passes, ci-build.yml sets the review-workflow commit status to success and posts a single comment confirming the PR carries no review lane.
4. A member of @usace-rmc/docs-admin merges.

No peer review, no Lead Civil review, no technical edit, no Director approval. If the build passes and an administrator agrees with the change, it ships.

What CODEOWNERS does and doesn't do

.github/CODEOWNERS lists protected paths — src/components/, src/theme/, scripts/, .github/, docusaurus.config.js, and others. Touching one of them auto-requests a review from @usace-rmc/docs-admin so the right people see the change.

It is not a merge requirement. Branch protection on main sets require_code_owner_reviews to false and requires zero approving reviews, so an unanswered code-owner request does not block the merge button. The two required status checks — CI Build and review-workflow — are the only hard gates.

Deploys

Merging to main triggers the production deploy when the change touches a path the deploy workflow watches: docs/, src/, static/, scripts/, docusaurus.config.js, tailwind.config.js, package.json, or package-lock.json. The deploy then pauses at the production environment gate for administrator approval, exactly as it does for documentation changes.

A PR that changes only files outside that list — a workflow under .github/, for instance — merges without deploying anything. A site administrator can always publish on demand with the workflow_dispatch trigger on the deploy workflow.

Mixed pull requests

A pull request that changes site code and content under docs/ is a documentation PR, because it touches docs/. Name the branch with the docs/ prefix matching the documentation change; otherwise the workflow cannot detect a lane and a site administrator has to assign one by hand.

Where the code change and the documentation change are unrelated, split them into two pull requests. The code change then merges on CI alone, while the documentation change goes through its lane without being held up.

Choosing the right lane

When in doubt, the author should choose the more conservative lane. A site administrator can reassign lanes by swapping lane:* labels.