docs: add CONTRIBUTING.md as 5-min onboarding for human or AI - #9
Merged
Conversation
A self-contained orientation that a fresh contributor — or a Claude Code session picking up an issue cold — can read in five minutes and then start opening PRs without re-discovering everything we learned during the bootstrap arc. - Mental model (SaaS-shaped, no hosts). - Read order across CLAUDE.md, README, state.md, ci.md, setup.md. - PR workflow: branch naming, commit format, PR title format, the 4 required status checks, the fork PR + safe-to-plan label dance. - "Where things go" table mapping the kind of change to the right leaf file. - Local dev quickstart with terraform login + plan. - API tricks: read HCP plan summary and confirm apply via API (no UI required). Same pattern we used throughout the bootstrap. - Three gotchas not in the design decisions: brittle HCP check name, GitHub Pages cert wedge, cf-terraforming-is-for-onboarding-only. - What not to do, including the policy against the claude.ai/code Co-Authored-By trailer. Pairs with Issue #8 (HCP-as-code) so the next session can pick that up without reconstructing context.
Two reusable patterns that appeared during the bootstrap arc but weren't written down: - docs/setup.md: replace the in-line "discovery token will need Read scopes" hedge with a full "Adding scopes to the Cloudflare token later" section. Key point: edit, don't regenerate — the value stays the same and HCP keeps working without re-pasting. - docs/import.md: add a "Discovery token" section before Install. Separate, short-lived, Read-only token; loaded onto the laptop via the read -s + /tmp/cf_token trick; revoked after the run. Same pattern we used for the email-routing arc, generalised. Both sections are what every future "I need to onboard another Cloudflare resource type" task will need.
4 tasks
hasansezertasan
added a commit
that referenced
this pull request
Jun 25, 2026
…it (#10) Expands the docs/ layer from "what this is" to "how to run it" with seven additions / extensions, plus an index so the surface stays navigable as it grows. Added: - docs/rollback.md — six ranked options when apply goes wrong: revert, discard, cancel, state surgery, admin override, rebuild. - docs/recipes.md — copy-paste recipes for the five tasks future-you will do most: add DNS record, add repo, add label, bump provider, cross-workspace change. - docs/limits.md — free-tier ceilings on HCP, Cloudflare, GitHub, Let's Encrypt with current usage and the cliffs to watch. - docs/hcp-api.md — REST API toolkit: workspace lookup, plan summary, confirm/discard/cancel, variable listing, manual plan trigger. Every script we used during the bootstrap, generalised and reusable. - docs/worktree-workflow.md — optional git worktree convention for maintainers juggling branches. - docs/README.md — index of every doc with a one-line hook and a reading order for first contact. Stops the docs surface from becoming a flat directory listing. Extended: - docs/secrets.md — Rotation section turned from one-line-per-credential into step-by- step zero-downtime procedures with "no plan, no revoke" verification. - terraform/README.md — Conventions section: lock file is committed, label naming, file-per- category split, provider pin policy (~> X.Y), cross-leaf references hedge. Pairs with #9 (CONTRIBUTING.md) and Issue #8 (HCP-as-code) so the next session can pick up either thread with full operational context, not just first-contact orientation.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A self-contained orientation that a fresh contributor — or a Claude Code session picking up an issue cold — can read in five minutes and then start opening PRs without re-discovering everything we learned during the bootstrap arc.
Contents
Test plan