Skip to content

docs: add docs/ scaffolding with ADR and runbook conventions#7

Merged
stoopidJSON merged 3 commits into
mainfrom
docs-init
May 2, 2026
Merged

docs: add docs/ scaffolding with ADR and runbook conventions#7
stoopidJSON merged 3 commits into
mainfrom
docs-init

Conversation

@stoopidJSON
Copy link
Copy Markdown
Contributor

@stoopidJSON stoopidJSON commented May 1, 2026

Establish the docs/ structure as the canonical location for project documentation that bridges business need and technical reality.

Adds:

  • docs/README.md: tech spec template covering overview, goals/non-goals, current state, solution, constraints, open questions, and glossary.
  • docs/adrs/: architectural decision records using an extended Michael Nygard format (Title, Status, Context, Decision, Consequences, Alternatives Considered). Includes README documenting when to write an ADR, the lifecycle, and numbering conventions.
  • docs/runbooks/: operational runbook template optimized for high-stress reading. Includes README codifying when to write one and the maintenance discipline (review-on-use, quarterly audit).

Each subdirectory contains both a curated README index and a template file. Templates use the same blockquote convention as the rest of the repository (delete-after-instantiation).

This is the foundation for follow-up work: Makefile generation targets (make adr / make runbook), CI-enforced docs hygiene (adr-lint with pre-commit and GitHub Actions integration), staleness detection, and broader documentation automation. Those land in subsequent commits to keep this change reviewable in isolation.

Todos

  • Tests
  • Documentation

Deploy Notes (optional)

Notes regarding deployment the contained body of work.

Steps to Test or Reproduce (optional)

Outline the steps to test or reproduce the PR here.

commands to test PR

Impacted Areas in Application (optional)

List general components of the application that this PR will affect:

Establish the docs/ structure as the canonical location for project
documentation that bridges business need and technical reality.

Adds:
- docs/README.md: tech spec template covering overview, goals/non-goals,
  current state, solution, constraints, open questions, and glossary.
- docs/adrs/: architectural decision records using an extended Michael
  Nygard format (Title, Status, Context, Decision, Consequences,
  Alternatives Considered). Includes README documenting when to write
  an ADR, the lifecycle, and numbering conventions.
- docs/runbooks/: operational runbook template optimized for
  high-stress reading. Includes README codifying when to write one
  and the maintenance discipline (review-on-use, quarterly audit).

Each subdirectory contains both a curated README index and a template
file. Templates use the same blockquote convention as the rest of the
repository (delete-after-instantiation).

This is the foundation for follow-up work: Makefile generation
targets (make adr / make runbook), CI-enforced docs hygiene
(adr-lint with pre-commit and GitHub Actions integration), staleness
detection, and broader documentation automation. Those land in
subsequent commits to keep this change reviewable in isolation.
@stoopidJSON stoopidJSON marked this pull request as draft May 1, 2026 18:09
Add .tool-versions as the source of truth for runtime versions, with
Makefile bootstrap detection and CONTRIBUTING.md updates to recommend
mise to new contributors.

Changes:
- .tool-versions: template file with conventions documented inline.
  All entries commented out; projects derived from this template
  uncomment the lines they need.
- Makefile: HAS_TOOLVERSIONS detection, bootstrap step that runs
  mise install (or asdf as fallback) when .tool-versions is present,
  graceful degradation with instructional message when neither
  tool is installed.
- CONTRIBUTING.md: prerequisites updated to recommend mise as the
  primary version manager. Existing language-specific manifests
  (package.json engines, pyproject.toml, etc.) are kept but framed
  as derivative of .tool-versions.

Eliminates the duplication of version specs across CONTRIBUTING.md,
CI workflows, Dockerfiles, and language manifests. Bumping a tool
version becomes a single-file change.
…ssions

The previous commitlint.yml combined PR title validation and commit
message validation in a single workflow under pull_request_target.
This caused two problems:

1. The amannn/action-semantic-pull-request action failed with
   "Resource not accessible by integration" because the workflow
   was missing the statuses: write permission required to post
   check results back to the PR.

2. The commits job ran under pull_request_target while explicitly
   checking out the PR head SHA. This is the pwn-request pattern:
   PR-author-supplied code (commitlint config, npm install scripts)
   would execute with the workflow's elevated permissions, allowing
   a malicious PR to compromise the repo.

Splits the validation into two workflows with appropriate triggers
and permission scopes:

- pr-title.yml: pull_request_target, reads PR metadata only, posts
  status check. Safe because the action never executes PR code.
- commit-lint.yml: pull_request, checks out PR code in its own
  reduced-permission context. The check result is the workflow
  exit code, no API write needed.

Branch protection rules should be updated to require both checks:
"PR Title Lint / PR title" and "Commit Lint / Commit messages".
The old "Commit Lint / PR title" and "Commit Lint / Commit messages"
check names will no longer exist.
@stoopidJSON stoopidJSON marked this pull request as ready for review May 2, 2026 16:13
@stoopidJSON stoopidJSON merged commit 4a19c32 into main May 2, 2026
20 of 22 checks passed
@stoopidJSON stoopidJSON deleted the docs-init branch May 2, 2026 16:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant