A Typical RFC Template
While RFC formats vary by organization, most effective RFCs share a common structure. Here is a template that works well for infrastructure and platform engineering proposals:
# RFC-0003: Migrate CI/CD Pipeline from Jenkins to GitHub Actions
## Meta
- **Author:** Jane Chen (Platform Team)
- **Reviewers:** @backend-leads, @sre-team, @security
- **Status:** In Review
- **Created:** 2024-06-01
- **Decision Deadline:** 2024-06-15
## Summary
A 2-3 sentence executive summary. Anyone should understand the proposal
after reading just this section.
"We propose migrating all CI/CD pipelines from our self-hosted Jenkins
cluster to GitHub Actions. This eliminates ~15 hours/week of Jenkins
maintenance, reduces build times by an estimated 40%, and aligns our
tooling with our existing GitHub-based workflow."
## Problem Statement
What specific problem are we solving? Include data.
"Our Jenkins cluster has experienced 3 outages in Q1 2024, each causing
2-4 hours of blocked deployments. The Jenkins controller runs on a single
EC2 instance with no HA configuration. Plugin compatibility issues after
upgrades have caused 2 additional incidents. The platform team spends
approximately 15 hours per week on Jenkins maintenance (patching, plugin
updates, agent management, troubleshooting)."
## Proposed Solution
Detailed technical description of the proposed approach. Include:
- Architecture diagrams
- Migration strategy (big bang vs. incremental)
- Timeline estimate
- Resource requirements
## Alternatives Considered
For each alternative, explain:
1. What it is
2. Why it was considered
3. Why it was rejected
### Alternative A: Upgrade Jenkins and add HA
- Adds complexity (Jenkins HA is notoriously difficult to configure correctly)
- Doesn't address the plugin ecosystem fragility
- Estimated effort: 3 weeks, ongoing maintenance unchanged
### Alternative B: Migrate to GitLab CI
- Would require migrating source code repositories to GitLab
- Team has no GitLab experience
- Estimated effort: 8 weeks (including repo migration)
### Alternative C: Migrate to Tekton on Kubernetes
- Cloud-native and highly flexible
- Steep learning curve; YAML-heavy pipeline definitions
- Estimated effort: 6 weeks
- Rejected because the team prioritizes simplicity over flexibility at
our current scale
## Risks and Mitigations
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| GitHub Actions outage blocks all deploys | Medium | High | Maintain emergency Jenkins fallback for 30 days post-migration |
| Workflow syntax differences cause migration bugs | High | Medium | Migrate one service first as a pilot; validate before proceeding |
| Cost overruns on GitHub Actions minutes | Low | Medium | Set billing alerts; use self-hosted runners for heavy workloads |
## Open Questions
- Do we need to support ARM-based builds? (Affects runner selection)
- What is the security team's policy on third-party GitHub Actions?
- Can we use GitHub's OIDC integration for AWS credential management?
## Decision
[Filled in after the review period ends]
Key differences from an ADR:
The RFC is deliberately longer and more detailed because its purpose is different. It needs to give reviewers enough information to evaluate the proposal critically. The "Open Questions" section is particularly important — it signals intellectual honesty and invites specific, targeted feedback rather than vague objections. An author who lists their own uncertainties is far more credible than one who presents a proposal as if it has no unknowns.
The Decision Deadline is a practice borrowed from Amazon's decision-making culture. Without a deadline, RFCs can languish in review indefinitely, blocking progress. A deadline forces reviewers to engage and forces the team to make a decision — even if that decision is "we need more information, extending the deadline by one week." Two weeks is a common default for most RFC reviews; complex cross-team proposals may warrant four weeks.
The RFC review process in practice:
- Author publishes the RFC (as a PR, a shared doc, or a wiki page) and notifies reviewers.
- Reviewers leave comments asynchronously over the review period.
- Author responds to comments, updates the RFC, and resolves open questions.
- At the deadline, the team lead or a designated decision-maker calls the decision.
- The final decision is recorded in the RFC's "Decision" section.
- A concise ADR is written to capture the outcome for long-term reference.
Key Point: The quality of an RFC is measured not by how convincing it is, but by how easy it is to critique. A well-written RFC makes it simple for reviewers to identify risks, challenge assumptions, and propose modifications. If reviewers can't find anything to push back on, the RFC is either perfect (unlikely) or not detailed enough to evaluate (much more likely). The best RFC authors actively solicit criticism: "I'm not confident about the cost estimate in section 3 — please challenge this if you have better data."