RFC Template

RFCs are a process of documenting proposal for technical change. It help to structure project architecture around collective discussions with your community.

This repository is a github template that will help you easily bootstrap your RFC book. You can view the demo at https://plab-io.github.io/project-rfcs-template/.

What's included

RFCs book setup using mdbook
RFC template at src/0000-rfc-template.md with example at src/rfcs/0000-awesome-rfc-template.md
RFC guide at src/rfcs/rfcs.md
Code Of Conduct form https://opensource.guide/code-of-conduct/
Contributor page
Github workflow to publish mdBook on github-pages

How to Use It

Use this repo as a template
Use bootstrap script replace the template variables

❯ ./bin/bootstrap.sh
Github Organization Name:
PLAB-IO

Repository Name:
project-rfcs-template

Contact in case of abuse report:
abuse@plab.io

Did you want remove rfc example?: [yes/no]
yes

rm 'src/rfcs/0000-awesome-rfc-template.md'

Following the guide instruction of section How to propose a new RFC

Contribution

If you have any question, recommendation, or improvement. Or even if you use this class and it's useful for you, thanks for taking a few minutes to open an issue and share your experience.

Fork :book:
Push :runner:
PR :clap:

RFC / Request For Comments

RFCs are a process of documenting proposal for technical change. It help to structure project architecture around collective discussions seeking feedback from the community. RFC are represented by the form of documents that try to be speculative and precise.

This template are heavily based on the famous Rust RFC Book

When you must NOT follow this process

Rephrasing, reorganizing, refactoring, or otherwise "changing shape does not change meaning".
Additions that strictly improve objective, numerical quality criteria (warning removal, speedup, better platform coverage, more parallelism, trap more errors, etc.)
Enhancement of a feature that does not change the behavior or introduce BC break.

If you submit a pull request to implement a new feature without going through the RFC process, it may be closed with a polite request to submit an RFC first.

When you must follow this process

You need to follow this process if you intend to make substantial changes such as:

API change that will break backward compatibility that is not a bugfix.
New features (not enhancement)
Removing features ( re-designed )
Change of dependencies that impact API ( critical system library )
Change of Standardization or Protocol (tcp to websocket, quic, cryptographic curve, hashing method...)

Before creating an RFC

An RFC process front-loads the collaborative work of major changes or additions to an open-source project. That is, instead of waiting until a pull request arrives with lines of code changes, discussion begins early. Contributors are required to put in effort up-front to help others in the project community understand their proposed changes. The project's TSC and its extended developer community are invited to provide input within the structure of the RFC.

Although there is no single way to prepare for submitting an RFC, it is generally a good idea to pursue feedback from other project developers beforehand, to ascertain that the RFC may be desirable; having a consistent impact on the project requires concerted effort toward consensus-building.

How to propose a new RFC

In order to ease the process, we have prepare a template that you can use to fill a proposal.

Copy the file 0000-rfc-template.md to rfcs/0000-my-feature.md (where "my-feature" is descriptive. don't assign an RFC number yet).
Fill in the RFC. Put care into the details: RFCs that do not present convincing motivation, demonstrate lack of understanding of the design's impact, or are disingenuous about the drawbacks or alternatives tend to be poorly-received.
Submit a pull request. As a pull request the RFC will receive design feedback from the larger community, and the author should be prepared to revise it in response.
At some point, a member of TSC (or other form of approval in this particular project) will approve or reject the proposal. It can also have a period for final comment (FCP) to notify that the process will end shortly. FCP period is quiet, and the RFC is either merged or closed. However, sometimes substantial new arguments or ideas are raised, the FCP is canceled, and the RFC goes back into development mode.

The RFC life-cycle

Once an RFC has been approved, it will be merged and automatically published on the website. Now that the RFC are active, it must be taken in the roadmap of the SDLC. In most of the case it will be implemented by the author of the RFC or any persons that seek interest to expedite the development of that RFC.

Feature Name: awesome_rfc_template
Start Date: 2020-05-22
RFC PR: plab/project-rfcs-template#1

Summary

Create a Github template that help people to bootstrap rapidly RFC repository with clear guideline and website generator.

Motivation

Why are we doing this? There are no such of Generic RFC template for open source project

What use cases does it support? Ease the access of deploying RFC repository for Open Source project

What is the expected outcome? Help community of open source project to organize better the design and evolution of their software.

Guide-level explanation

Explain the proposal as if it was already implemented and you need to write documentation about it for other to use it easily. That generally means:

Introducing new named concepts.
Explaining the feature largely in terms of examples.

Reference-level explanation

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.

Drawbacks

Why should we not do this?

Rationale and alternatives

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?

Related issues

Link issues that has been opened and already discussed topic that match your RFC

Contributor Covenant Code of Conduct

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

Demonstrating empathy and kindness toward other people
Being respectful of differing opinions, viewpoints, and experiences
Giving and gracefully accepting constructive feedback
Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

The use of sexualized language or imagery, and sexual attention or advances of any kind
Trolling, insulting or derogatory comments, and personal or political attacks
Public or private harassment
Publishing others' private information, such as a physical or email address, without their explicit permission
Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at abuse@plab.io. All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

Contributors

Here is a list of the contributors who participate in the project.

Jane Done