This should contain a brief (3-5 sentences) description of the mission of your project. The goal is to state what you are planning to work on and help external contributors understand roughly which types of features will likely be welcome for this project.
See also mission statement chapter in Producing Open Source Software.
This section should contain brief documentation written for first time users on how to get started using the project. Further more detailed documentation can be linked to from here.
This section can list any or all of the following:
A list of features, use cases that the software addresses.
Information on design principles that are used to resolve trade-offs
Links to further user level documentation
Answers to frequently asked questions (FAQ), preferably in a format that allows to link to specific questions and their answers for easier reference.
This section should contain a brief documentation on how to get help for the project as a user. This could be as simple as pointing users to the issue tracker if this is how your project would like to answer questions. It could also point to an archived and searchable chat channel, some archived searchable mailing list, some online user forum.
This section should include information on how to get in touch with the project: Typically this will contain links to archived, searchable and linkable communication channels.
This is a good place to give credit to Trusted Committers of the project.
It's also a good place to include information on what being a Trusted Committer means for this project - although ideally all projects in an organization use the same definition that is only linked to from here. The reason to keep the link here is for colleagues who have no or little experience with working in and contributing to InnerSource projects to have a direct link back to company wide information from the technological projects they need for their daily work.
This section should document (or link to documentation) on all things that a first time contributor needs to know to get started. Typically not all of the topics below will be covered. Focus on what differs in your project from standard setup and what previous contributors found hard to understand.
Finding the source code.
Finding a list of issues that your project needs help with - these can be both, technical and non-technical issues. Typically you will keep those in an issue tracker accessible to contributors.
Links to further documentation e.g. about the architecture of the project, general coding conventions, testing conventions...
Ideally you also include information on what the preferred process for changes looks like for the project: Should contributors first open an issue and submit a proposal, or are they welcome to submit changes right away? What is important to you when reviewing contributions?
In addition you should outline any design values you want to follow in the project. Making those explicit often helps resolve trade-offs more quickly and more easily. In addition it helps making changes to otherwise implicit assumptions transparent.
Over time you will notice that this section grows substantially. In that case think about moving the information to separate files, e.g. a CONTRIBUTING.md and TESTING.md.
Submitting your changes back to the project.
Feature Name: (fill me in with a unique identifier, my_awesome_feature)
Start Date: (fill me in with today's date, YYYY-MM-DD)
Nominated owners: (Representatives of technical ownership areas affected by the RFC. This will often be tech leads, but they may delegate. RFCs cannot be accepted until all nominated owners have signed off.)
One paragraph explanation of the feature.
This section is essential to allow us to learn from the things we are implementing.
When is the retrospective?
[ ] Retro completed?
(where/how it will be held, how can people get involved, where are the results?)
Why are we doing this? What use cases does it support? What is the expected outcome?
Explain the proposal as if it was already existing and you were teaching it to another engineer. That generally means:
Introducing new named concepts.
Explaining the feature largely in terms of examples.
Explaining how engineers should think about the feature. It should explain the impact as concretely as possible.
If applicable (e.g. code/architecture proposal), provide sample error messages, deprecation warnings, or migration guidance.
For implementation-oriented RFCs, this section should focus on how contributors should think about the change, and give examples of its concrete impact. For policy/process RFCs, this section should provide an example-driven introduction to the policy/process, and explain its impact in concrete terms.
This is the technical portion of the RFC. Explain the design in sufficient detail that:
Its interaction with other features is clear.
It is reasonably clear how the feature would be implemented.
Corner cases are dissected by example.
The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work.
Why should we not do this?
Why is this design the best in the space of possible designs?
What other designs have been considered and what is the rationale for not choosing them?
What is the impact of not doing this?
Discuss prior art, both the good and the bad, in relation to this proposal. A few examples of what this can include are:
For language, library, tools etc: Does this feature exist in other places and what experience have their community had?
For community proposals: Is this done by some other community and what were their experiences with it?
For other teams: What lessons can we learn from what other communities have done here?
Papers: Are there any published papers or great posts that discuss this? If you have some relevant papers to refer to, this can serve as a more detailed theoretical background.
This section is intended to encourage you as an author to think about the lessons from other places, provide readers of your RFC with a fuller picture. If there is no prior art, that is fine - your ideas are interesting to us whether they are brand new or if it is an adaptation from other places.
What parts of the design do you expect to resolve through the RFC process before this gets merged?
What parts of the design do you expect to resolve through the implementation of this feature before stabilization?
What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC?
Think about what the natural extension and evolution of your proposal would be and how it would affect the teams and projects as a whole in a holistic way. Try to use this section as a tool to more fully consider all possible interactions with the project and teams in your proposal. Also consider how the this all fits into the roadmap for the project and of the relevant sub-team. This is also a good place to "dump ideas", if they are out of scope for the RFC you are writing but otherwise related. If you have tried and cannot think of any future possibilities, you may simply state that you cannot think of anything. Note that having something written down in the future-possibilities section is not a reason to accept the current or a future RFC; such notes should be in the section on motivation or rationale in this or subsequent RFCs. The section merely provides additional information.
If applicable, describe the differences between teaching this to existing engineers and new engineers.
Put an individual COMMUNICATION.md file tailored to the project in each repo. If project repo ownership is transferred to a different team in the future, they need to be able to access and edit documentation related to the project. This includes documentation that outlines the communication processes that users should use to contact the team.
Delete top paragraph when this section is filled out.
Team Slack channel:
Special Slack Channels: (topic specific and accessible to anyone who would be an external contributor)
Team Email:
The following types of actions can be moved to the appropriate section and more added.
Managers or roles and specific situations they should be contacted for outside the team channel.
(this is set up this way so that the document can easily be changed if there are new members on the team)
Tell how to find the owner, responsible party, or group people should contact if they have questions about documentation in the repo.
Describe this communication process.
For example:
If you have questions on a specific piece of documentation, you can find the team member responsible for the information by looking here:
You can contact the responsible party by sending a message in the xyz channel, send them a direct message in chat, email, etc. The individual who last certified the documentation is the responsible party.
Traffic specific changes (e.g. team to team, etc.)
New Feature rollout
As per product guidelines
Month end and company wide code freeze
Internal team and any other teams who contribute to team project repos
Add more…
Contact Method
(email or slack channel)
Bug report
Feature request
Contribution process questions
Merge Requests after submission
Add more here…
Status updates
other
other
Add more here...
Breaking changes (for e.g. any changes to our API or messaging contracts)
Extended/planned outages (service downtime for maintenance related activities)
Unexpected Outages
Provide information on what kinds of contributions your project is looking for here. For example these can be bug reports, help with answering user questions, improving documentation, fixes to bugs, as well as new feature implementations.
Add information on how to submit bug reports here. This should include hints about which type of information the project will need in order to reproduce and fix issues. It can also include information on commonly found misconfigurations that look like bugs.
Also include information on what contributors can expect in terms of time to first response and process after that.
Add information on how to submit feature requests here. Also include information on what contributors can expect in terms of time to first response and process after that.
Include information on any documentation best practices your project follows as well as how to build documentation, checks to run and how to submit the changes made back to the project.
This section should contain information on
How to access the project source code,
General project layout,
Any requirements to the development environment,
Code formatting guidelines,
This section should make the process for becoming a Trusted Committer explicit if that route is open to contributors.
This section serves as a reminder to existing and explanation for new Trusted Committers detailing how to add others to the host team. Again ideally this information is identical for all projects in the organization so central information can be linked to from here.
How to run the test suite.