You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 41122ac
Browse filesBrowse the repository at this point in the historyBrowse files
`src/docConfig.js` is the central registry for every published document tile. Each entry has two orthogonal flags:
62
+
63
+
-`active`: `true` means the doc is built, served, sidebar-registered, and indexed by Algolia. `false` means the doc is excluded from the prod build and renders as a "Coming Soon" tile on the landing page; in dev (`DOCS_MODE=dev`) it still builds so contributors can work on it.
64
+
-`draft`: `true` renders a diagonal "DRAFT" watermark on the **latest version only** of the doc (older versions stay unwatermarked). `false` means no watermark.
65
+
66
+
The two flags are orthogonal — a doc can be `active: true, draft: true` (published with watermark) or `active: false, draft: true` (unpublished but flagged for future watermarking).
- Version paths: `docs/{category}/{app}/{type}/v{major}.{minor}/`
79
103
- Special files: `00-document-info.mdx`, `00-version-history.mdx`
80
104
105
+
## Branching and Review Workflow
106
+
107
+
The `main` branch is protected. All changes go through a pull request. Branch prefixes auto-assign the PR to one of five review lanes via the `stage-progression.yml` GitHub workflow:
108
+
109
+
| Prefix | Lane | Reviews required |
110
+
|---|---|---|
111
+
|`docs/new/`| New document | Peer → Lead Civil → Technical edit → Director |
112
+
|`docs/major/`| Major revision (new major version) | Peer → Lead Civil |
113
+
|`docs/minor/`| Minor revision (new minor version) | Peer |
|`docs/dev/`| Dev docs (anything under `docs/dev/`) | None (admin self-merge) |
116
+
117
+
Dev-docs detection is also content-based: any PR whose changed files under `docs/` are all under `docs/dev/` is auto-routed to `lane:dev` regardless of branch name.
118
+
119
+
Branch protection on `main` requires two status checks:
120
+
-`CI Build` — runs `npm run build` on every PR
121
+
-`review-workflow` — set by `stage-progression.yml`; flips to success when the PR reaches `stage:ready-to-merge` (or immediately for `lane:editorial-fix` and `lane:dev`)
122
+
123
+
Full details: [docs/dev/documentation-guide/](docs/dev/documentation-guide/) chapters 09–15.
124
+
81
125
## Code Style
82
126
83
127
- Prettier: 150 char line width, single quotes, trailing commas
- Do NOT include "Co-Authored-By: Claude", "Claude Code", or any AI/assistant attribution in commit messages
90
134
- Keep commit messages concise and focused on the changes made
91
135
92
-
## Claude Code Skills
93
-
94
-
This repository includes Claude Code skills (slash commands) in `.claude/skills/`. Reference files for skills are in `.claude/skills/*.md` (e.g., `git-conventions.md`).
-**Level 1**: Do NOT suggest rewording or technical changes—syntax and grammar only
121
148
-**Level 2**: Do NOT suggest improvements beyond matching the source document
122
149
-**Level 3**: Full editorial suggestions allowed; mark these as "Editorial" category with "Suggestion" severity
123
150
- All levels: Do NOT edit MDX files directly—output findings to `qc/` only
124
151
152
+
The standardized prompt for the formal in-PR technical edit is at [.github/ai-review/technical-editor-prompt.md](.github/ai-review/technical-editor-prompt.md) — see Documentation Guide chapter 13 for how it's invoked.
Copy file name to clipboardExpand all lines: README.md
+14-40Lines changed: 14 additions & 40 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ The project includes:
12
12
13
13
The project is organized to support easy contribution, internal consistency, and extensibility across future RMC documentation needs.
14
14
15
-
For development standards, file structure, custom components, and styling conventions, please refer to the internal [Documentation Guide](https://usace-rmc.github.io/RMC-Software-Documentation/docs/documentation-guide/introduction/)
15
+
For development standards, file structure, custom components, and styling conventions, please refer to the internal [Documentation Guide](https://usace-rmc.github.io/RMC-Software-Documentation/docs/documentation-guide/introduction/).
16
16
17
17
The guide includes:
18
18
@@ -21,51 +21,25 @@ The guide includes:
21
21
- Tailwind utility conventions and shared styles
22
22
- Table formatting and counter file integration
23
23
- Versioning strategy and linking guidelines
24
+
- The full review and approval workflow for all documentation changes
24
25
25
-
## Claude Code Skills
26
+
## Review and Approval Workflow
26
27
27
-
This repository includes Claude Code skills (slash commands) in `.claude/skills/` for common development workflows. Skills are invoked with `/{name}` in a Claude Code session.
28
+
All changes to documentation go through a pull request against the protected `main` branch. The branch prefix determines which of five review lanes the PR is routed to:
28
29
29
-
### Git & Repository
30
+
| Branch prefix | Lane | Reviews required |
31
+
|---|---|---|
32
+
|`docs/new/`| New document | Peer → Lead Civil → Technical edit → Director |
33
+
|`docs/major/`| Major revision (new major version) | Peer → Lead Civil → Technical edit |
34
+
|`docs/minor/`| Minor revision (new minor version) | Peer → Technical edit |
|`docs/dev/`| Dev docs (anything under `docs/dev/`) | None (admin self-merge) |
30
37
31
-
| Skill | Description |
32
-
|-------|-------------|
33
-
|`/commit`| Stage changes and create a git commit following project conventions |
34
-
|`/push`| Push current branch to remote with safety checks |
35
-
|`/commit-push`| Commit and push in a single operation |
36
-
|`/pr`| Create a GitHub pull request with auto-generated title and description |
37
-
|`/review-pr`| Review a pull request for code quality, MDX patterns, and documentation standards |
38
+
Each PR receives an automatic preview build at an unadvertised URL where reviewers read the rendered document. Branch protection on `main` requires both the `CI Build` and `review-workflow` status checks to pass before merge, so the merge button reflects the workflow's judgment automatically.
38
39
39
-
### Page Verification & Quality
40
+
For details on each lane, who reviews what, and step-by-step instructions for authors, reviewers, the Director, and site administrators, see chapters 9 through 15 of the [Documentation Guide](https://usace-rmc.github.io/RMC-Software-Documentation/docs/documentation-guide/introduction/).
40
41
41
-
| Skill | Description |
42
-
|-------|-------------|
43
-
|`/smoke-test`| Quick health check — page loads, no console errors, no broken images |
44
-
|`/review-responsive`| Screenshot and analyze a page at 7 device viewports (desktop through phone) |
45
-
|`/review-page`| Full page audit combining Lighthouse scores with responsive design review |
46
-
|`/check-accessibility`| Section 508 / WCAG AA compliance audit using Lighthouse + Playwright |
47
-
|`/check-performance`| Lighthouse performance audit with Core Web Vitals and resource analysis |
48
-
|`/lint-fix`| Run ESLint, auto-fix issues, and provide guidance for remaining problems |
49
-
50
-
### Documentation & QC
51
-
52
-
| Skill | Description |
53
-
|-------|-------------|
54
-
|`/qc-review`| Run a QC review at Level 1, 2, or 3 on an MDX document (wraps `qc/qc-prompt.md`) |
55
-
|`/build`| Run the Docusaurus production build and analyze errors/warnings |
56
-
|`/check-links`| Scan MDX files for broken references, missing images, and orphaned keys |
@@ -258,20 +268,24 @@ This is regular text with **bold** and _italic_ formatting.
258
268
259
269
## Common Contribution Workflows
260
270
271
+
The `main` branch is protected. Every change goes through a feature branch and a pull request. The branch prefix routes the PR to one of five review lanes — see [Review Lanes](./10-review-lanes.mdx) for the full mapping.
272
+
261
273
### Workflow 1: Convert Existing Word Document
262
274
263
275
**Use case:** You have an existing RMC document in Word format that needs to be converted to MDX.
264
276
265
277
**Steps:**
266
278
267
-
1. Place Word document in `static/source-documents/`
268
-
2. Run DOCX converter script to generate MDX files
269
-
3. Review and refine generated MDX files
270
-
4. Add generated files to appropriate `docs/` folder
271
-
5. Test locally with `npm start`
272
-
6. Commit changes to Git
279
+
1. Create a `docs/new/<slug>` branch off `main`.
280
+
2. Place the Word document in `static/source-documents/`.
281
+
3. Run the DOCX converter script to generate MDX files.
282
+
4. Review and refine generated MDX files.
283
+
5. Add generated files to the appropriate `docs/` folder.
284
+
6. Register the document in `src/docConfig.js` with `active: false, draft: true`.
285
+
7. Test locally with `npm start`.
286
+
8. Commit, push the branch, and open a pull request. The review workflow auto-assigns Lane 1 (peer → Lead Civil → technical edit → Director).
273
287
274
-
**Typical time:** 1-3 hours depending on document complexity
288
+
**Typical time:** 1-3 hours depending on document complexity.
275
289
276
290
---
277
291
@@ -283,19 +297,20 @@ This is regular text with **bold** and _italic_ formatting.
283
297
284
298
For a detailed, step-by-step guide to creating a new document from scratch, see [Chapter 04: Creating a New Document - Complete Walkthrough](./04-creating-new-document-walkthrough.mdx).
285
299
286
-
The walkthrough includes folder setup, asset organization, administrator coordination, testing procedures, and complete examples.
300
+
The walkthrough includes folder setup, asset organization, testing procedures, and complete examples.
287
301
288
302
:::
289
303
290
304
**High-Level Steps:**
291
305
292
-
1. Determine folder location based on hierarchy (see [Complete Walkthrough](./04-creating-new-document-walkthrough.mdx))
293
-
2. Create all folder structures (docs/, static/figures/, static/videos/, static/bibliographies/)
5. Create MDX files (using the DOCX converter or manually).
311
+
6. Register the document in `src/docConfig.js` with `active: false, draft: true`.
312
+
7. Test locally with `npm start`.
313
+
8. Commit, push, and open a PR. The review workflow auto-assigns Lane 1 and guides you through peer → Lead Civil → technical edit → Director review (see [Author Workflow](./11-author-workflow.mdx)).
299
314
300
315
**For detailed instructions, templates, real-world examples, and troubleshooting, use the [comprehensive walkthrough](./04-creating-new-document-walkthrough.mdx).**
301
316
@@ -305,23 +320,27 @@ The walkthrough includes folder setup, asset organization, administrator coordin
305
320
306
321
**Use case:** You need to update an existing document for a new software version or to correct errors.
307
322
308
-
**For minor edits (typos, small clarifications):**
323
+
**For typos and editorial fixes (Lane 4):**
324
+
325
+
1. Create a `docs/fix/<slug>` branch off `main`.
326
+
2. Edit the existing version's MDX files directly.
327
+
3. Test locally.
328
+
4. Commit, push, and open a PR. The site admin will review and merge — no formal peer review required.
329
+
330
+
**For minor revisions / new minor version (Lane 3):**
309
331
310
-
1. Edit the existing version's MDX files directly
311
-
2. Test locally
312
-
3. Commit changes
332
+
1. Create a `docs/minor/<slug>-v<version>` branch off `main`.
333
+
2. Create the new version folder (e.g., `v1.1/`) by copying the previous version.
334
+
3. Mirror the version structure for figures, bibliography, and source documents.
335
+
4. Make your updates and flip `draft: true` on the document's entry in `src/docConfig.js`.
336
+
5. Test locally.
337
+
6. Commit, push, and open a PR. The workflow assigns Lane 3 (peer review → technical edit).
313
338
314
-
**For major updates (new features, substantial changes):**
339
+
**For major revisions / new major version (Lane 2):**
315
340
316
-
1. Create new version folders (e.g., `v1.1/`)
317
-
2. Copy all files from previous version
318
-
3. Make updates to the new version
319
-
4. Add new images to corresponding `static/figures/` version folder
320
-
5. Update `bib.json` if needed
321
-
6. Test locally
322
-
7. Commit changes
341
+
Same as Lane 3 but on a `docs/major/<slug>-v<version>` branch. The workflow adds an RMC Lead Civil review stage between peer review and the technical edit.
323
342
324
-
**Typical time:** 30 minutes to 2 hours depending on scope
343
+
**Typical time:** 30 minutes to a few hours depending on scope. Review turnaround adds days; plan accordingly.
0 commit comments