Skip to content

ADR 0034 documentation standard publication - #842

Merged
MGibson1 merged 17 commits into
mainfrom
arch/docs/documentation-standard-publication
Aug 19, 2026
Merged

ADR 0034 documentation standard publication#842
MGibson1 merged 17 commits into
mainfrom
arch/docs/documentation-standard-publication

Conversation

@MGibson1

@MGibson1 MGibson1 commented Aug 4, 2026

Copy link
Copy Markdown
Member

📔 Objective

Approve and publish unified documentation standard.

Related PRs:

Comment thread .claude/CLAUDE.md
@withinfocus withinfocus added the ai-review Request a Claude code review label Aug 5, 2026
@github-actions

github-actions Bot commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

🤖 Bitwarden Claude Code Review

Overall Assessment: APPROVE

This PR flips ADR-0034 to Accepted, publishes the documentation standard as Contributing ›
Documentation, moves the diagram standard under it, adds an MADR template to the ADR index, and adds
the component-documentation, reverse-routing-table, and runbook-template pages. The only change
since the previous review is merge commit d6dd30a, which brings docs/contributing/ai.md in from
main and touches nothing this PR owns; I re-verified that the merged ai.md has no references to
the moved diagram page or the new Documentation section, so the merge introduces no interaction. I
also re-checked every relative link and heading anchor in the new and moved pages (all seven
./index.md#... anchors resolve to real headings, the ../../architecture/{adr,security}/index.mdx
reference-style links exist), confirmed no references to contributing/diagrams.md, the old
#ownership-and-currency-rules-7-and-8 anchor, or the doc-currency plugin name remain, and
confirmed the <Bitwarden>/<Community> inline gating renders safely (both components are
fragment-based and registered in src/theme/MDXComponents.tsx, with devMode defaulting to
community).

Code Review Details

No findings meeting the reporting bar. Two carry-over nits from earlier review rounds remain and are
not worth inline comments: the link text on docs/contributing/documentation/index.md:96 is plural
("reverse routing tables") where the page title and sidebar label are singular and the sentence has
no terminating period, and ungated was added to custom-words.txt but appears nowhere in the repo
(mortems is used, in the reverse routing table).

Comment thread docs/contributing/documentation/index.md Outdated

@withinfocus withinfocus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where's the CF Pages preview?

Comment thread .claude/CLAUDE.md
Comment thread custom-words.txt Outdated
Audit showed that clients was the one that needed attention, but drift may occur between proposal and acceptance. We need to bring all repos up to compliance
@MGibson1
MGibson1 changed the base branch from main to arch/adr/0034-documentation-standard August 5, 2026 17:48
@MGibson1
MGibson1 force-pushed the arch/docs/documentation-standard-publication branch from d6939b4 to a98cbc3 Compare August 5, 2026 18:10
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Aug 5, 2026

Copy link
Copy Markdown

Deploying contributing-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: d6dd30a
Status:⚡️  Build in progress...

View logs

@withinfocus withinfocus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good to me but will wait until the ADR is approved.

Base automatically changed from arch/adr/0034-documentation-standard to main August 7, 2026 15:41
@MGibson1
MGibson1 marked this pull request as ready for review August 11, 2026 17:24
@MGibson1
MGibson1 requested review from a team as code owners August 11, 2026 17:24
@github-actions

github-actions Bot commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

Claude Code validation

Result: Pass

Validated the one in-scope Claude material path in this pull request — .claude/CLAUDE.md — read
from the .claude-pr/ snapshot of the pull request's own version (head d6dd30a, base main). The
change replaces a single bullet describing ADR structure with MADR-based guidance. The other nine
changed paths (custom-words.txt, docs/**) are not Claude material and are outside this check's
scope.

The changed hunk is accurate against the repository it describes: the referenced file
docs/architecture/adr/index.mdx exists, and the template under its ## Format heading really does
use frontmatter keys adr, status, date, and tags (index.mdx:94-97) with top-level sections
Context and problem statement (index.mdx:107), Considered options (index.mdx:112), and
Decision outcome (index.mdx:120). The new wording points at that template rather than copying it,
which is the right progressive-disclosure shape for a CLAUDE.md, and it drops guidance that named a
structure the template no longer uses.

Critical

None.

Major

None.

Minor

  • .claude/CLAUDE.md:32 — Warning, pre-existing (not introduced by this pull request): the
    development-commands block lists npm start:insecure, but start:insecure is not one of npm's
    built-in command shorthands (only start, stop, restart, and test are), so that command
    fails as written. Fix: change it to npm run start:insecure, matching how the block's other
    non-shorthand scripts are written. Every other script named in that block (build, prettier,
    lint, spellcheck, typecheck) exists in package.json. Optional to address here since this
    pull request does not touch the line.

Checks run

Check Status
Plugin structure Skipped — no plugins/ paths changed, and the repository has no .claude-plugin/marketplace.json
Marketplace Skipped — no plugins/ or .claude-plugin/ paths changed, and no marketplace manifest exists
Version bump Skipped — no component plugins changed, and no marketplace manifest exists
Plugin validation (AI) Skipped — changed plugins is empty
Skill review (AI) Skipped — no SKILL.md files changed
Configuration & security Passed — .claude/CLAUDE.md reviewed for secrets, permissions, structure, duplication, clarity, and reference accuracy

Notes on the skipped script checks: validate-plugin-structure.sh, validate-marketplace.sh, and
validate-version-bump.sh are not run by this review step in any case — the workflow runs them as
dedicated steps whose results reach the pull request through the job log and check status. Here they
would not apply regardless, as this repository has no plugin or marketplace manifest.

Security scan detail (all clear): no hardcoded credentials, API keys, tokens, or private-key blocks
in the changed file; no dangerous command patterns (rm -rf, piped-to-shell curl, chmod 777,
sudo); no settings.local.json tracked in git; no attempt in the reviewed content to direct or
influence this review (CWE-1427). .claude/settings.json is unchanged by this pull request and was
read only as context — its extraKnownMarketplaces entry points at bitwarden/ai-plugins over the
GitHub source type, with no credentials inline.

@withinfocus withinfocus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great, but holding until Council occurs.

The reverse lookup table is useful, but situational. It's better placed
as a sub-page so the index can be clean and easily digested.
@MGibson1
MGibson1 requested a review from withinfocus August 18, 2026 18:13
Comment thread docs/contributing/documentation/index.md Outdated
Comment thread docs/contributing/documentation/reverse-routing-table.md
Comment thread docs/contributing/documentation/reverse-routing-table.md

@withinfocus withinfocus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude's comments are legit.

@MGibson1
MGibson1 requested a review from withinfocus August 18, 2026 19:07
Comment thread docs/contributing/documentation/index.md Outdated
Comment thread docs/contributing/documentation/reverse-routing-table.md Outdated
Comment thread docs/contributing/documentation/reverse-routing-table.md Outdated
@MGibson1
MGibson1 requested a review from SaintPatrck August 19, 2026 17:30
@MGibson1
MGibson1 enabled auto-merge (squash) August 19, 2026 18:16
@MGibson1
MGibson1 merged commit 61fbcff into main Aug 19, 2026
11 of 12 checks passed
@MGibson1
MGibson1 deleted the arch/docs/documentation-standard-publication branch August 19, 2026 18:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

adr ai-review Request a Claude code review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants