docs: absorb DORA docs repo into forgejo-mcp/docs/

ldraney commented

2026-06-13 18:57:11 +00:00

Owner

Summary

Moves 4 DORA documentation files from the standalone ldraney/DORA repo into forgejo-mcp/docs/. Git is the heart of DORA, forgejo-mcp wraps the Forgejo API — docs belong here, not in a separate docs-only repo. README updated with docs table.

Changes

Added docs/architecture.md — data flow diagrams, component details, deployment definitions
Added docs/metrics.md — all 4 Prometheus metric families with labels and example PromQL
Added docs/tiering.md — Tier 1/2/3 repo classification and implementation options
Added docs/dashboard.md — current Grafana panels, queries, and 5 planned improvements
Updated README.md — added DORA Docs table linking to local docs

Test Plan

Docs render correctly in Forgejo web UI
Mermaid diagrams render in architecture.md and tiering.md
README docs table links resolve

Review Checklist

No code changes — docs only
Content migrated as-is from ldraney/DORA
No new dependencies

project-dora-metrics — updated with action-vs-measurement architecture this session.

Closes #29

## Summary Moves 4 DORA documentation files from the standalone ldraney/DORA repo into forgejo-mcp/docs/. Git is the heart of DORA, forgejo-mcp wraps the Forgejo API — docs belong here, not in a separate docs-only repo. README updated with docs table. ## Changes - Added docs/architecture.md — data flow diagrams, component details, deployment definitions - Added docs/metrics.md — all 4 Prometheus metric families with labels and example PromQL - Added docs/tiering.md — Tier 1/2/3 repo classification and implementation options - Added docs/dashboard.md — current Grafana panels, queries, and 5 planned improvements - Updated README.md — added DORA Docs table linking to local docs ## Test Plan - [ ] Docs render correctly in Forgejo web UI - [ ] Mermaid diagrams render in architecture.md and tiering.md - [ ] README docs table links resolve ## Review Checklist - [x] No code changes — docs only - [x] Content migrated as-is from ldraney/DORA - [x] No new dependencies ## Related Notes project-dora-metrics — updated with action-vs-measurement architecture this session. Closes #29

ldraney added 1 commit

2026-06-13 18:57:11 +00:00

docs: absorb DORA docs repo into forgejo-mcp/docs/

ci/woodpecker/push/woodpecker Pipeline was successful

Details

ci/woodpecker/pr/woodpecker Pipeline was successful

Details

59b9f108f6

The standalone ldraney/DORA repo was docs-only (4 markdown files). Since
git/Forgejo is the heart of DORA and forgejo-mcp wraps the Forgejo API,
these docs belong here. Adds architecture, metrics reference, tiering,
and dashboard specs. README updated with docs table.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ldraney commented

2026-06-13 18:59:01 +00:00

Author

Owner

PR #30 Review

Title: docs: absorb DORA docs repo into forgejo-mcp/docs/
Parent issue: #29
Type: Docs-only (0 code changes, 471 additions, 0 deletions across 5 files)

DOMAIN REVIEW

This is a documentation-only PR. No code, no tests, no infra changes. The domain is technical documentation for a DORA metrics pipeline (Prometheus exporter, Grafana dashboards, project tiering).

Content quality assessment:

docs/architecture.md (105 lines) -- Well-structured. Two Mermaid diagrams (data flow and Prometheus integration) are clean and readable. The "What Deployment Means" table is a strong addition that clarifies a definition gap. Secrets block in the Prometheus diagram names specific env vars (WOODPECKER_URL, WOODPECKER_TOKEN, etc.) -- these are secret names, not secret values, so no credential exposure.
docs/metrics.md (91 lines) -- Excellent reference doc. All 4 metric families documented with type, labels, source, description, and example PromQL. The "Known Gaps" table at the bottom is honest and actionable. The PromQL examples are syntactically correct and use proper functions (histogram_quantile, rate, clamp_min).
docs/tiering.md (155 lines) -- The tier system is well-reasoned. Mermaid diagram is clear. Three implementation options are compared with a clear recommendation (Option A). The Grafana integration section with example PromQL is a good forward reference. One observation: the YAML config example and JSON dashboard variable snippet are hypothetical/planned -- they describe future state, not current state. This is acceptable for a design doc but could benefit from a note marking them as planned.
docs/dashboard.md (111 lines) -- Good documentation of current state vs. planned improvements. The PromQL table covers all 9 current panel queries. The 5 planned improvements are concrete and actionable. The DORA band thresholds table (Elite/High/Medium/Low) is a useful reference.
README.md -- Docs table is clean, with correct relative paths. Placement between the existing DORA architecture section and the Auth section is logical.

BLOCKERS

None.

This is a docs-only PR. The BLOCKER criteria (untested code, unvalidated input, secrets, DRY violations in auth) do not apply to documentation. No credentials or secrets are committed -- the docs reference secret names and env var names only.

NITS

docs/tiering.md, line 118-130: The YAML config and JSON dashboard variable are presented as current examples but describe future/planned state. Consider a brief callout (e.g., "Planned configuration:" or a note) to distinguish these from documentation of existing behavior. This is minor since the surrounding context ("Implementation" section with "Option A: recommended") already signals this is a proposal.
docs/dashboard.md, line 16: The "Problem" note about tier filtering could include a cross-reference to docs/tiering.md where the solution is detailed. Helps readers navigate.
Consistency: docs/architecture.md references file paths in other repos (pal-e-platform/terraform/modules/monitoring/main.tf, pal-e-platform/terraform/dashboards/dora-dashboard.json). These cross-repo references are useful context but will silently go stale if those paths change. No action needed now, but worth noting for future maintenance.
docs/metrics.md, Known Gaps table: The "Fix" column for "No rework rate metric" says "Forgejo PR review event collector" -- this is terse. A brief expansion would help future readers understand the path forward.

SOP COMPLIANCE

PR body has ## Summary -- present, clear
PR body has ## Changes -- present, lists all 5 files
PR body has ## Test Plan -- present (3 manual verification items)
PR body has ## Related -- present (references project-dora-metrics, closes #29)
No secrets, .env files, or credentials committed
No unnecessary file changes (all 5 files are in scope for the stated goal)
Branch naming follows convention: 29-absorb-dora-docs
Commit message prefix: docs: -- appropriate for docs-only change

PROCESS OBSERVATIONS

Repo consolidation: Absorbing standalone docs into the repo they describe is the right call. A standalone ldraney/DORA repo with only markdown files creates indirection without adding value. Docs next to code is the standard pattern.
No test impact: Docs-only, no test plan needed beyond render verification. The manual test plan items (Mermaid rendering, link resolution) are appropriate.
Deployment frequency: This PR is low-risk and should merge quickly. No CI impact.
Forward references: Several docs describe planned/future state (tier labels, dashboard improvements). This is fine for planning docs but the team should track which improvements get implemented and update these docs accordingly, or they will drift.

VERDICT: APPROVED

## PR #30 Review **Title:** docs: absorb DORA docs repo into forgejo-mcp/docs/ **Parent issue:** #29 **Type:** Docs-only (0 code changes, 471 additions, 0 deletions across 5 files) --- ### DOMAIN REVIEW This is a documentation-only PR. No code, no tests, no infra changes. The domain is **technical documentation** for a DORA metrics pipeline (Prometheus exporter, Grafana dashboards, project tiering). **Content quality assessment:** 1. **docs/architecture.md** (105 lines) -- Well-structured. Two Mermaid diagrams (data flow and Prometheus integration) are clean and readable. The "What Deployment Means" table is a strong addition that clarifies a definition gap. Secrets block in the Prometheus diagram names specific env vars (WOODPECKER_URL, WOODPECKER_TOKEN, etc.) -- these are secret *names*, not secret *values*, so no credential exposure. 2. **docs/metrics.md** (91 lines) -- Excellent reference doc. All 4 metric families documented with type, labels, source, description, and example PromQL. The "Known Gaps" table at the bottom is honest and actionable. The PromQL examples are syntactically correct and use proper functions (histogram_quantile, rate, clamp_min). 3. **docs/tiering.md** (155 lines) -- The tier system is well-reasoned. Mermaid diagram is clear. Three implementation options are compared with a clear recommendation (Option A). The Grafana integration section with example PromQL is a good forward reference. One observation: the YAML config example and JSON dashboard variable snippet are hypothetical/planned -- they describe future state, not current state. This is acceptable for a design doc but could benefit from a note marking them as planned. 4. **docs/dashboard.md** (111 lines) -- Good documentation of current state vs. planned improvements. The PromQL table covers all 9 current panel queries. The 5 planned improvements are concrete and actionable. The DORA band thresholds table (Elite/High/Medium/Low) is a useful reference. 5. **README.md** -- Docs table is clean, with correct relative paths. Placement between the existing DORA architecture section and the Auth section is logical. --- ### BLOCKERS None. This is a docs-only PR. The BLOCKER criteria (untested code, unvalidated input, secrets, DRY violations in auth) do not apply to documentation. No credentials or secrets are committed -- the docs reference secret *names* and env var *names* only. --- ### NITS 1. **docs/tiering.md, line 118-130**: The YAML config and JSON dashboard variable are presented as current examples but describe future/planned state. Consider a brief callout (e.g., "Planned configuration:" or a note) to distinguish these from documentation of existing behavior. This is minor since the surrounding context ("Implementation" section with "Option A: recommended") already signals this is a proposal. 2. **docs/dashboard.md, line 16**: The "Problem" note about tier filtering could include a cross-reference to `docs/tiering.md` where the solution is detailed. Helps readers navigate. 3. **Consistency**: `docs/architecture.md` references file paths in other repos (`pal-e-platform/terraform/modules/monitoring/main.tf`, `pal-e-platform/terraform/dashboards/dora-dashboard.json`). These cross-repo references are useful context but will silently go stale if those paths change. No action needed now, but worth noting for future maintenance. 4. **docs/metrics.md, Known Gaps table**: The "Fix" column for "No rework rate metric" says "Forgejo PR review event collector" -- this is terse. A brief expansion would help future readers understand the path forward. --- ### SOP COMPLIANCE - [x] PR body has ## Summary -- present, clear - [x] PR body has ## Changes -- present, lists all 5 files - [x] PR body has ## Test Plan -- present (3 manual verification items) - [x] PR body has ## Related -- present (references project-dora-metrics, closes #29) - [x] No secrets, .env files, or credentials committed - [x] No unnecessary file changes (all 5 files are in scope for the stated goal) - [x] Branch naming follows convention: `29-absorb-dora-docs` - [x] Commit message prefix: `docs:` -- appropriate for docs-only change --- ### PROCESS OBSERVATIONS - **Repo consolidation**: Absorbing standalone docs into the repo they describe is the right call. A standalone ldraney/DORA repo with only markdown files creates indirection without adding value. Docs next to code is the standard pattern. - **No test impact**: Docs-only, no test plan needed beyond render verification. The manual test plan items (Mermaid rendering, link resolution) are appropriate. - **Deployment frequency**: This PR is low-risk and should merge quickly. No CI impact. - **Forward references**: Several docs describe planned/future state (tier labels, dashboard improvements). This is fine for planning docs but the team should track which improvements get implemented and update these docs accordingly, or they will drift. --- ### VERDICT: APPROVED