How rust-lang/rfcs works
Project type and purpose
• This is a documentation-driven repository of “Request for Comments” (RFC) documents for Rust, organized and published as an “RFC Book.”
• It is not a traditional full-stack app but rather a static-site generator pipeline: authors write Markdown RFCs, CI builds them into a browsable book, and the result is deployed as a website.
File structure
• Top level:
• book.toml – configuration for mdBook
• generate-book.py – helper script to assemble and preprocess the book
• text/ – directory containing numbered Markdown RFCs
• README.md, LICENSE-APACHE, LICENSE-MIT – documentation and licensing
• .github/workflows/deploy.yml – GitHub Actions CI/CD pipeline
• triagebot.toml, renovate.json5 – automated bots configurations
• No “frontend” or “backend” folders; instead, the repo is both the source and the build scripts for a static site.
• CI config triggers on merges and pull requests, runs the build script, then deploys to GitHub Pages (the published RFC Book).
README
• Describes the RFC process and links to sub-team guidelines.
• No runtime architecture but implies:
• “Fork → PR → review → merge” workflow
• “generate-book.py” + mdBook compile → static HTML output
• Deployment to GitHub Pages.
Main components
a. Contributors (local Git)
b. GitHub repository (source of Markdown, CI workflows, bot configs)
c. GitHub Actions CI server
d. Static site generator stage:
– generate-book.py (Python orchestration)
– mdBook toolchain (Rust-based static site generator)
e. Artifacts: HTML/CSS/JS static site
f. Hosting: GitHub Pages (or alternative static-host)
g. Bots/External services:
– renovate bot (dependency updates)
– triagebot (issue/PR triage)
Component relationships and data flow
• Contributor pushes branch or PR → GitHub repo
• GitHub Actions is triggered by commits/PRs → runs generate-book.py → calls mdBook → produces HTML
• On “deploy” branch or on merge to main, CI pushes built site to GitHub Pages
• renovate bot periodically scans repository → opens dependency PRs
• triagebot watches issues/PRs → posts labels/comments based on triagebot.toml
Architectural patterns and design principles
• CI/CD pipeline (GitOps style) for automated documentation publishing
• Static site generation for high performance and low operational overhead
• Git-centric workflow for collaboration and change tracking
• Bot-driven automation for dependency upkeep and PR triage
Technology & frameworks
• GitHub Actions
• mdBook (Rust)
• Python (“generate-book.py”)
• GitHub Pages
• Renovate (JS-based dependency bot)
• Triagebot (Rust bot for RFC repo)
Detail
• Every major file or tool that plays a part in producing the final site.
• Don’t oversimplify—break the pipeline into at least these stages: source → CI orchestration → static-site generation → deployment → hosting.
• Where automated maintenance tools (renovate, triagebot) hook into the repo.