| author | state | changed |
|---|---|---|
Allan Jude <[email protected]>, George V. Neville-Neil <[email protected]>, Benno Rice <[email protected]> |
accepted |
2017-06-09T16:20+0000 |
The FreeBSD project has adopted a model of discussion and collaboration for major changes called FreeBSD Community Proposals, or FCPs. This model is based on Requests for Comments (RFCs) that originated with the IETF.
FCPs use the Markdown format for text formatting.
FCPs use the IETF interpretations of the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" as defined in RFC 2119.
The rest of this FCP documents when, why, and how to write an FCP.
The purpose of the FCP process is to document the design decisions behind proposed changes and gather feedback from the many different types of users that make up the FreeBSD community about how a change will impact them.
There are no strict rules as to when an FCP should be written, but here are some examples of when creating an FCP is a good idea:
- A change lacks consensus or is significantly contended.
- Creating, changing, or removing a feature is likely to cause user confusion, a violation of the Principle of Least Astonishment (POLA).
- A change breaks the behavior of existing commands or libraries.
- A substantive change to the behavior or function of the ports or packaging system.
- A change significantly impacts how people interact with the FreeBSD community.
- A change that is proposed or committed which results in significant objections SHOULD use the FCP process to come to a resolution.
- Proposing a change to FreeBSD community tools or processes.
Every FCP MUST have a title that is a simple synopsis of the document. FCPs are dated to allow the title to change. An FCP MUST have the following attributes:
- Title: A simple synopsis of the document. The title may change as the FCP evolves.
- Date: [YYYYMMDD] An easy numerical reference to the FCP. MUST be the date the proposal was first introduced.
- Metadata: Information to track the authors and state of the FCP.
An FCP SHOULD address these questions:
Clearly describe the problem with enough detail for someone unfamiliar with the issue to understand the proposed solution. Give a description and discussion of the problem first. Follow this with a separate description and discussion of the proposed solution. Keep the problem and solution descriptions and discussions separate for clarity.
Examples of problems are:
- The lack of a feature.
- A needed improvement to an existing feature.
- An ambiguity in the functionality of the system.
- An issue with a community process.
How will this change affect users? How will it affect existing scripts or other integrations with the system? How will it impact programs that link against base system libraries?
All users of the system MUST be considered. FreeBSD is used by many individuals as well as directly and indirectly by many larger organizations and these MUST be taken into account.
If a public interface such as a command line program or its arguments, a library, or a syscall is to be changed, list it here along with a brief description of the intended change.
Changes to private interfaces, those consumed by other internal parts of FreeBSD, MUST also be listed with a similarly brief description of the intended change.
What are the implications to current users of FreeBSD if they upgrade their systems to a newer version that includes this change? Can the change be merged to the stable branch? Any such changes MUST be added to the UPDATING file in the main FreeBSD repository.
What potentially untrusted user input, whether data or code, will be handled by the system as part of the change? Which components will interact with that input? How will that input be validated and managed securely? What new or changed privileges will your feature require? How can the new code be sandboxed? How might an attacker use the proposed facilities to escalate their privileges?
An FCP can be in one of the following states:
- draft
- feedback
- vote
- accepted
- rejected
- withdrawn
An FCP is first created in the draft state. Before publicizing
the FCP to the mailing lists, the author is encouraged to contact
[email protected] for editorial review. When the draft is ready, it moves
to the feedback state and is published to the [email protected] mailing list
and CCed to other appropriate forums like related technical lists.
The feedback state is where all discussion of the FCP takes place. Various
contributors will provide feedback on the changes proposed in the FCP and their
impact on the FreeBSD project. FCPs MAY have code attached to them, whether
example code or a reference to a set of patches that can be reviewed.
When the discussion of a change has come to a suitable and acceptable close it
SHOULD be updated to the vote state.
At this time the FreeBSD Core Team will vote on the subject of the FCP. The
result of vote moves the FCP into the accepted or rejected state.
FCPs in the accepted state can be updated and corrected.
See the "Changes after acceptance" section for more information.
The authors may withdraw an FCP at any time. If an FCP is not
viable or if an FCP is to be ignored, it can be moved into the withdrawn
state.
To create a new FCP, an author MUST take the following steps.
A template is provided in the FCP repository. FCPs MUST have a text width of 80 columns. Extra material such as code samples, graphs, and other materials may be provided and MUST be named starting with the FCP filename like this:
fcp-YYYYMMDD-shortname_code-sample-1.c
Every FCP document MUST start with a brief amount of metadata in the python-markdown2 metadata format as follows:
---
authors: Committer Name <[email protected]>,
Collaborator Name <collaborator@example>
state: draft
changed: 2017-06-09T15:17+0000
---
Only authors and state values are tracked. There MAY be any number of
authors. Author entries MUST contain both name and e-mail address for
proper attribution. A changed entry SHOULD be present and indicate the date
the FCP was last modified. If present this attribute MUST be in
ISO 8601
format and in the UTC time zone. An appropriate
timestamp can be generated with this command:
$ date -u +%Y-%m-%dT%H:%M%z
The FCP MUST be published under a filename of the form:
fcp-YYYYMMDD-XXXX.md
The XXXX MUST be replaced with a short name to idenify the subject of the FCP.
The FCP MUST then be added to the
FCP repository either using the functionality
provided on the Github website or by creating a branch and raising a pull
request. Adding the FCP to the repository SHOULD be done in the same pull request
as adding it to the index.md. If the author lacks
a GitHub account or needs assistance they SHOULD contact [email protected].
The FCP must be added to the repository in the draft state.
After the FCP has been published, the author should seek input from the
[email protected] list and any other contributors or forums that seem
appropriate. If this feedback results in edits to the FCP these edits MUST
be reflected in the FCP repository as soon as practical. The changed metadata
attribute, if present, MUST be kept up to date.
When the author feels an FCP is complete, it
can move on to the feedback state described below.
Feedback begins when the FCP document itself and the FCP index
document in the repository are updated to indicate that the FCP is in the
feedback state. The FCP MUST then be announced on the [email protected] list
and any other forums, like topic-specific mailing lists, that are appropriate
to the content of the FCP.
The subject of the announcement MUST include the FCP filename and title. The body of the announcement MUST include a link to the FCP along with a summary which can be any abstract or summary from the document itself.
As the feedback process continues, any edits to the FCP MUST be reflected in
the repository copy as soon as is practical. The changed metadata attribute,
if present, MUST be kept up to date.
After the feedback process has concluded, the author MUST request a vote on the
FCP by updating the FCP itself and the index to indicate it is in the
vote state. The FCP author MUST also notify [email protected]. The email
to core MUST have the FCP filename and title in the subject line and a summary
of the FCP along with a link to the repository copy of the FCP in the body.
The author SHOULD provide pointers to relevant discussion on the FCP in the
various forums where it has been discussed.
Core MAY request more information if it is needed to inform their vote. Core MAY also notify the author that additional time is needed to deliberate. If core has not specifically requested additional time, core MUST complete its deliberation and voting process within two weeks.
The core vote will result in the FCP being moved to either the accepted or
rejected states. This state MUST be reflected in the FCP document and in
the index. Core MAY add a section to the FCP detailing the reasoning behind
their decision.
At any point prior to the resolution of the core vote, the
author MAY withdraw their FCP. If an FCP is withdrawn it MUST be indicated in
the FCP itself and the FCP index by changing the FCP state to withdrawn.
The author MAY add a section to the FCP detailing the reasoning behind the
withdrawal.
FCPs may need revision after they have been moved into the accepted
state. In such cases, the author SHOULD update the FCP to reflect the final conclusions. If
the changes are major, the FCP SHOULD be withdrawn and restarted.