docs: add RFC process for design discussions; fix post-#83 review notes#84
Open
marcelocra wants to merge 2 commits into
Open
docs: add RFC process for design discussions; fix post-#83 review notes#84marcelocra wants to merge 2 commits into
marcelocra wants to merge 2 commits into
Conversation
Introduce docs/rfcs/ for the living discussion that precedes (and often outlives) a decision: problem, context, options considered, and an append-only discussion log — including verbatim AI pairing excerpts, which is exactly the context that gets lost when only the final decision is kept. ADRs stay short and final; RFCs hold the process. docs/archives/ is left untouched as the informal precursor to this. RFC 0001 captures the '[script]/route.ts does two things' discussion from the #83 review (embedded bash-with-interpolation, and scripts: vs. templates: being two mechanisms for the same job) without resolving it, per request. ADR 0006 and its own README now link to it. Site fixes from the same review round: - install-scripts.yml: clarify the scripts: vs. templates: comment (they look identical without one), update the editorconfig description to match the expanded template, and link the comment to RFC 0001 - install-scripts page: render backtick-quoted text in descriptions as actual inline code instead of literal backticks; add id anchors to each card for deep-linking - home page: new 'More Templates & Scripts' section listing every script/template as a chip linking to /install-scripts#id, so the catalog is discoverable from the home page (it wasn't linked from anywhere in the site) - footer: add a Templates & Scripts link next to Features - README: mention the --proto '=https' --tlsv1.2 curl hardening flags (same ones rustup uses) as an optional, more defensive install command Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LuKjgTCp3QuvUWqxPf7Q1y
Sources consulted while designing the RFC convention weren't saved anywhere outside the chat. Add a Further Reading section listing them, including a company-examples piece the reader found independently (Airbnb/Amazon/Stedi templates) that complements the newsletter piece already cited. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LuKjgTCp3QuvUWqxPf7Q1y
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
Greptile SummaryThis PR adds an RFC process and surfaces the installer catalog more clearly. The main changes are:
Confidence Score: 5/5This looks safe to merge.
Important Files Changed
Reviews (1): Last reviewed commit: "docs: save the RFC/ADR research referenc..." | Re-trigger Greptile |
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
2 participants
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
Two things: a home for design discussions (as requested), and a handful of small fixes from reviewing merged PR #83.
docs/rfcs/— design discussionsIntroduces the missing piece between "just a
TODO.md" and the existing ADRs: a place for the process of reaching a decision (problem, context, every option considered, an append-only discussion log — including verbatim excerpts from AI pairing sessions), as distinct from ADRs, which stay short and record only the result.docs/rfcs/README.md— explains RFC vs. ADR vs.docs/archives/(the informal precursor to this convention, left untouched), when to bother writing one, the format, and a Further Reading section with the sources behind this design (Pragmatic Engineer's RFC/ADR workflow piece, a company-examples survey, a broader design-doc-practices gist, and the OpenBMC design doc guidelines).docs/rfcs/template.md— Problem, Context, Discussion Log, Options Considered, Open Questions, Decision, Related.docs/rfcs/0001-unify-installer-implementation.md— a real first entry, capturing (verbatim) the "[script]/route.tsdoes two structurally different things" discussion from the feat: generic project-template installer #83 review, deliberately left unresolved (Status: Exploring) per request. ADR 0006 and its README now link to it both ways.Fixes from the #83 review
install-scripts.yml— clarified thescripts:vs.templates:comment (they looked identical without one; now states the real distinguishing factor — arbitrary logic vs. plain file copy — and links to RFC 0001); updated theeditorconfigdescription to match the expanded template (PHP/Laravel, Rust, Dockerfiles,nushell)./install-scriptspage — backtick-quoted text in descriptions (e.g.`prettier`) now renders as real inline<code>instead of literal backticks; each card gets anidanchor for deep-linking./install-scripts#id, reading the same registry the catalog page uses (no duplicated content). The catalog page wasn't linked from anywhere in the site before this.--proto '=https' --tlsv1.2as an optional hardenedcurlinvocation (same flags rustup uses).Test plan
pnpm run buildpasses/and/install-scriptsin both locales: chips render, link to the right anchors, anchors exist on the target cards, inline code renders correctly, editorconfig description updatedNotes
[script]/route.tsitself is untouched, as requested; RFC 0001 tracks it for later.🤖 Generated with Claude Code
https://claude.ai/code/session_01LuKjgTCp3QuvUWqxPf7Q1y
Generated by Claude Code