28 KiB
| FEP | Title | Author | Discussions-To | Status | Type | Date | toc | ||
|---|---|---|---|---|---|---|---|---|---|
| 1 | FEP Purpose and Guidelines | Stanislav Bogatyrev <realloc@realloc.spb.ru> |
|
Active | Process | 2023-04-17 | true |
What is a FEP?
FEP stands for FrostFS Enhancement Proposal. The idea and most of the process is derived from Python PEP-1. Almost all text was simply copied and modified.
A FEP is a design document providing information to the FrostFS community, or describing a new feature for FrostFS or its processes or environment. The FEP should provide a concise technical specification of the feature and a rationale for the feature.
We intend FEPs to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that have gone into FrostFS. The FEP author is responsible for building consensus within the community and documenting dissenting opinions.
Because the FEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal. This historical record is available by the normal git commands for retrieving older revisions, and can also be browsed in frostfs.info repository. The current rendered version is available on frostfs.info site.
FEP Audience
The typical primary audience for FEPs are the FrostFS Core and Service developers, Architecture Committee, as well as developers of applications relying on FrostFS or using it's parts.
However, other parts of the FrostFS community may also choose to use the process (particularly for Informational FEPs) to document expected API conventions and to manage complex design coordination problems that require collaboration across multiple projects.
FEP Types
There are three kinds of FEP:
-
A Standards Track FEP describes a new feature or implementation for FrostFS. It may also describe an interoperability standard that will be supported outside the standard API for current FrostFS versions before a subsequent FEP adds support for that API in a future version.
-
An Informational FEP describes a FrostFS design issue, or provides general guidelines or information to the community, but does not propose a new feature. Informational FEPs do not necessarily represent a FrostFS community consensus or recommendation, so users and implementers are free to ignore Informational FEPs or follow their advice.
-
A Process FEP describes a process surrounding FrostFS, or proposes a change to (or an event in) a process. Process FEPs are like Standards Track FEPs but apply to areas other than the FrostFS itself. They may propose an implementation, but not to FrostFS's codebase; they often require community consensus; unlike Informational FEPs, they are more than recommendations, and community members are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in FrostFS development.
FEP Workflow
Starting with an idea
There are several references in this FEP to the "Architecture Committee", "Community Committee", "Committers" and "Developers". The detailed roles and project governance description is available in FEP-X (FrostFS Project Governance).
The FEP process begins with a new idea for the FrostFS stack. It is highly recommended that a single FEP contain a single key proposal or new idea; the more focused the FEP, the more successful it tends to be. Most enhancements and bug fixes don't need a FEP and can be submitted directly to the project's issue tracker for the corresponding repository. The Architecture Committee reserves the right to reject FEP proposals if they appear too unfocused or too broad. If in doubt, split your FEP into several well-focused ones.
Each FEP must have a champion -- someone who writes the FEP using the style and format described below, shepherds the discussions in the appropriate issues or chats, and attempts to build community consensus around the idea. The FEP author should first attempt to ascertain whether the idea is feasible for the new FEP. Creating an issue in appropriate repository with 'idea' or 'discussion' label is usually the best way to go about this, unless a more specialized venue is appropriate.
Vetting an idea publicly before going as far as writing a FEP is meant to save the potential author time. Asking the FrostFS community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions (searching the internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the author. Just because an idea sounds good to the author does not mean it will work for most people in most areas where FrostFS is used.
Once the champion has asked the community as to whether an idea has any chance of acceptance, a draft FEP should be presented to the appropriate venue mentioned above. This gives the author a chance to flesh out the draft FEP to make properly formatted, of high quality, and to address initial concerns about the proposal.
Submitting a FEP
Following the above initial discussion, the workflow varies based on whether any of the FEP's co-authors are Committers. If one or more of the FEP's co-authors are Committers, they are responsible for following the process outlined below. Otherwise (i.e. none of the co-authors are Committers), then the FEP author(s) will need to find a sponsor for the FEP.
Ideally, a Committer sponsor is identified, but non-Committer sponsors may also be selected with the approval of the Architecture Committee. Members of the "Committers" and "Architecture Committee" teams are pre-approved to be sponsors. The sponsor's job is to provide guidance to the FEP author to help them through the logistics of the FEP process (somewhat acting like a mentor). Being a sponsor does not disqualify that person from becoming a co-author. The sponsor of a FEP is recorded in the "Sponsor:" field of the header.
Once the sponsor or the Committer(s) co-authoring the FEP deem the document ready for submission, the proposal should be submitted as a draft FEP via a Pull request in frostfs.info repository. The draft must be written in FEP style as described below, else it will fail review immediately (although minor errors may be corrected by the editors).
The standard FEP workflow is:
-
You, the FEP author, fork the frostfs.info repository, and create a file named
content/proposals/<type>/fep-X.mdthat contains your new FEP. Use "X" as your draft FEP number. -
In the "Type:" header field, enter "Standards Track", "Informational", or "Process" as appropriate, and for the "Status:" field enter "Draft". For full details, see [FEP Header Preamble]({{<ref "#fep_header_preamble">}}).
-
Push this to your git repository fork and submit a pull request.
-
The FEP editors review your PR for structure, formatting, and other errors. Approval criteria are:
- It sound and complete. The ideas must make technical sense. The editors do not consider whether they seem likely to be accepted.
- The title accurately describes the content.
- The FEP's language (spelling, grammar, sentence structure, etc.) and code style should be correct and conformant. FEPs with invalid markup will not be approved.
Editors are generally quite lenient about this initial review, expecting that problems will be corrected by the reviewing process.
Note: Approval of the FEP is no guarantee that there are no embarrassing mistakes! Correctness is the responsibility of authors and reviewers, not the editors.
If the FEP isn't ready for approval, an editor will send it back to the author for revision, with specific instructions, using pull requests mechanism.
-
Once approved, Architecture Committee will assign your FEP a number.
Once the review process is complete, and the FEP editors approve it (note that
this is not the same as accepting your FEP!), they will squash commit your
pull request onto the master branch.
The FEP editors will not unreasonably deny publication of a FEP. Reasons for denying FEP status include duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the FrostFS philosophy. The Architecture Committee can be consulted during the approval phase, and are the final arbiter of a draft's FEP-ability.
As updates are necessary, the FEP author can check in new versions if they (or a collaborating developer) have write access to the FEP repository. Getting a FEP number assigned early can be useful for ease of reference, especially when multiple draft FEPs are being considered at the same time.
Standards Track FEPs consist of two parts, a design document and a reference implementation or prototype with proof of concept. It is generally recommended that at least a prototype implementation be co-developed with the FEP, as ideas that sound good in principle sometimes turn out to be impractical when subjected to the test of implementation.
Discussing a FEP
As soon as a FEP number has been assigned and the draft FEP is committed to the
FEP repository, a discussion thread for the FEP should be created to provide a
central place to discuss and review its contents, and the FEP should be updated
so that the Discussions-To header links to it. Normally it should be an
issue or Pull Request.
If a FEP undergoes a significant re-write or other major, substantive changes to
its proposed specification, a new issue should typically be created to solicit
additional feedback. If this occurs, the Discussions-To link must be updated
and a new Post-History entry added pointing to this new thread.
FEP authors are responsible for collecting community feedback on a FEP before submitting it for review. However, to avoid long-winded and open-ended discussions, strategies such as soliciting private or more narrowly-tailored feedback in the early design phase, collaborating with other community members with expertise in the FEP's subject matter, and picking an appropriately-specialized discussion for the FEP's topic (if applicable) should be considered. FEP authors should use their discretion here.
Once the FEP is assigned a number and committed to the FEP repository, substantive issues should generally be discussed in corresponding pull request reviews or issues. This ensures everyone can follow and contribute, avoids fragmenting the discussion, and makes sure it is fully considered as part of the FEP review process. Comments, support, concerns and other feedback on this designated thread are a critical part of what the Architecture Committee or FEP-Delegate will consider when reviewing the FEP.
FEP Review & Resolution
Once the authors have completed a FEP, they may request a review for style and consistency from the FEP editors. However, content review and acceptance of the FEP is ultimately the responsibility of the Architecture Committee or Community Committee, which is formally initiated by opening a Pull Request once the authors determine the FEP is ready for final review and resolution.
To expedite the process in selected cases (e.g. when a change is clearly beneficial and ready to be accepted, but the FEP hasn't been formally submitted for review yet), the Architecture Committee or Community Committee may also initiate a FEP review, first notifying the FEP author(s) and giving them a chance to make revisions.
For a FEP to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. The enhancement must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate the system unduly. Finally, a proposed enhancement must follow the spirit of decentralization and reliability in order to be accepted by the Architecture or Community Committees. (However, the spirit is an imprecise description; it may be defined as whatever is acceptable to the Committee. This logic is intentionally circular.)
Once a FEP has been accepted, the reference implementation must be completed. When the reference implementation is complete and incorporated into the main source code repository, the status will be changed to "Final".
To allow gathering of additional design and interface feedback before committing to long term stability for data storage format, protocols or API, a FEP may also be marked as "Provisional". This is short for "Provisionally Accepted", and indicates that the proposal has been accepted for inclusion in the reference implementation, but additional user feedback is needed before the full design can be considered "Final". Unlike regular accepted FEPs, provisionally accepted FEPs may still be Rejected or Withdrawn even after the related changes have been included in a FrostFS release.
Wherever possible, it is considered preferable to reduce the scope of a proposal to avoid the need to rely on the "Provisional" status (e.g. by deferring some features to later FEPs), as this status can lead to version compatibility challenges in the wider FrostFS ecosystem.
A FEP can also be assigned the status "Deferred". The FEP author or an editor can assign the FEP this status when no progress is being made on the FEP. Once a FEP is deferred, a FEP editor can reassign it to draft status.
A FEP can also be "Rejected". Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact. The "Withdrawn" status is similar - it means that the FEP author themselves has decided that the FEP is actually a bad idea, or has accepted that a competing proposal is a better alternative.
When a FEP is Accepted, Rejected or Withdrawn, the FEP should be updated accordingly. In addition to updating the Status field, at the very least the Resolution header should be added with a direct link to the relevant post making a decision on the FEP.
FEPs can also be superseded by a different FEP, rendering the original obsolete. This is intended for Informational FEPs, where version 2 of an API can replace version 1.
The possible paths of the status of FEPs are as follows:
While not shown in the diagram, "Accepted" FEPs may technically move to "Rejected" or "Withdrawn" even after acceptance. This will only occur if the implementation process reveals fundamental flaws in the design that were not noticed prior to acceptance of the FEP. Unlike Provisional FEPs, these transitions are only permitted if the accepted proposal has not been included in a FrostFS release - released changes must instead go through the regular deprecation process (which may require a new FEP providing the rationale for the deprecation).
Some Informational and Process FEPs may also have a status of "Active" if they are never meant to be completed. E.g. [FEP-1]({{< ref "/proposals/proc/fep-0001"
}}) (this FEP 😄).
FEP Maintenance
In general, FEPs are no longer substantially modified after they have reached the Accepted, Final, Rejected or Superseded state. Once resolution is reached, a FEP is considered a historical document rather than a living specification. Formal documentation of the expected behavior should be maintained elsewhere, such as the API specification.
If changes based on implementation experience and user feedback are made to Standards track FEPs while in the Provisional or (with Committee approval) Accepted state, they should be noted in the FEP, such that the FEP accurately describes the implementation at the point where it is marked Final.
Active (Informational and Process) FEPs may be updated over time to reflect changes to development practices and other details. The precise process followed in these cases will depend on the nature and purpose of the FEP in question.
Occasionally, a Deferred or even a Withdrawn FEP may be resurrected with major updates, but it is often better to just propose a new one.
What belongs in a successful FEP?
Each FEP should have the following parts/sections:
-
Preamble -- RFC-2822 style headers in Hugo page level params format containing meta-data about the FEP, including the FEP number, a short descriptive title (limited to a maximum of 44 characters), the names, and optionally the contact info for each author, etc.
-
Abstract -- a short (~200 word) description of the technical issue being addressed.
-
Motivation -- The motivation is critical flor FEPs that want to change the FrostFS protocols, data formats, API, or ecosystem. It should clearly explain why the existing specification is inadequate to address the problem that the FEP solves. This can include collecting documented support for the FEP from important projects in the FrostFS ecosystem. FEP submissions without sufficient motivation may be rejected.
-
Rationale -- The rationale fleshes out the specification by describing why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other systems.
The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.
-
Specification -- The technical specification should describe the semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations.
-
Backwards Compatibility -- All FEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The FEP must explain how the author proposes to deal with these incompatibilities. FEP submissions without a sufficient backwards compatibility treatise may be rejected outright.
-
Security Implications -- If there are security concerns in relation to the FEP, those concerns should be explicitly written out to make sure reviewers of the FEP are aware of them.
-
How to Teach This -- For a FEP that adds new functionality or changes system behavior, it is helpful to include a section on how to teach users, new and experienced, how to apply the FEP to their work.
-
Reference Implementation -- The reference implementation must be completed before any FEP is given status "Final", but it need not be completed before the FEP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details.
-
Rejected Ideas -- Throughout the discussion of a FEP, various ideas will be proposed which are not accepted. Those rejected ideas should be recorded along with the reasoning as to why they were rejected. This both helps record the thought process behind the final version of the FEP as well as preventing people from bringing up the same rejected idea again in subsequent discussions.
In a way this section can be thought of as a breakout section of the Rationale section that is focused specifically on why certain ideas were not ultimately pursued.
-
Open Issues -- While a FEP is in draft, ideas can come up which warrant further discussion. Those ideas should be recorded so people know that they are being thought about but do not have a concrete resolution. This helps make sure all issues required for the FEP to be ready for consideration are complete and reduces people duplicating prior discussion.
-
Footnotes -- A collection of footnotes cited in the FEP, and a place to list non-inline hyperlink targets.
-
Copyright/license -- Each new FEP must be placed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC BY-NC-SA 4.0).
FEP Formats and Templates
FEPs are UTF-8 encoded text files using the Markdown format in a dialect used by Hugo static site generator. Markdown allows for rich markup that is still quite easy to read, but also results in good-looking and functional HTML.
The FEP text files are automatically converted to HTML for easier online reading at FrostFS site
FEP Header Preamble
Each FEP must begin with an RFC-2822 style preamble in Hugo page level params format. The headers must appear in the following order. Headers marked with "*" are optional and are described below. All other headers are required.
FEP: <fep number>
Title: <fep title>
Author: <list of authors' real names and optionally, email addrs>
* Sponsor: <real name of sponsor>
Discussions-To: <URL of current canonical discussion thread>
Status: <Draft | Active | Accepted | Provisional | Deferred | Rejected |
Withdrawn | Final | Superseded>
Type: <Standards Track | Informational | Process>
Date: <date created on, in yyyy-mm-dd format>
* Requires: <fep numbers>
* Replaces: <fep number>
* Superseded-By: <fep number>
The Author header lists the names, and optionally the email addresses or GitHub/Codeberg/TrueCloudab Forgejo handles of all the authors/owners of the FEP. The format of the Author header values must be:
Random J. User <random@example.com>
if the email address is included, and just:
Random J. User
if the address is not given.
If there are multiple authors, each should be on a separate line as defined in YAML list format, like:
Author:
- Random J. User <random@example.com>
- Snegurocka (@snegurochka-chan)
The Sponsor field records which Committer or developer (approved by the Architecture Committees) is sponsoring the FEP. If one of the authors of the FEP is a Committer then no sponsor is necessary and thus this field should be left out.
The Discussions-To header provides the URL to the relevant discussion thread for the FEP. Normally an issue or Pull Request. For email lists, this should be a direct link to the thread in the list's archives, rather than just a mailto: or hyperlink to the list itself.
The Type header specifies the type of FEP: Standards Track, Informational, or Process.
The Date header records the date that the FEP was assigned a number. Dates
should be in yyyy-mm-dd format, e.g. 2023-02-01.
FEPs may have a Requires header, indicating the FEP numbers that this FEP depends on.
FEPs may also have a Superseded-By header indicating that a FEP has been rendered obsolete by a later document; the value is the number of the FEP that replaces the current document. The newer FEP must have a Replaces header containing the number of the FEP that it rendered obsolete.
Auxiliary Files
FEPs may include auxiliary files such as diagrams. All support files may be
placed in a subdirectory called fep-XXXX, where "XXXX" is the FEP number.
When using a subdirectory, there are no constraints on the names used in files.
Changing Existing FEPs
Draft FEPs are freely open for discussion and proposed modification, at the
discretion of the authors, until submitted to the corresponding Committee for
review and resolution. Substantive content changes should generally be first
proposed on the FEP's discussion thread listed in its Discussions-To header,
while copyedits and corrections can be submitted as an issue or Pull
Request. FEP authors with write access to the FEP repository can update the FEPs
themselves by using a PR to submit their changes. For guidance on
modifying other FEPs, consult the [FEP Maintenance]({{<ref
"#fep_maintenance">}}) section.
See the Contributing Guide for additional details, and when in doubt, please check first with the FEP author and/or a FEP editor.
Transferring FEP Ownership
It occasionally becomes necessary to transfer ownership of FEPs to a new champion. In general, it is preferable to retain the original author as a co-author of the transferred FEP, but that's really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the FEP process, or has fallen off the face of the 'net (i.e. is unreachable or not responding to email). A bad reason to transfer ownership is because the author doesn't agree with the direction of the FEP. One aim of the FEP process is to try to build consensus around a FEP, but if that's not possible, an author can always submit a competing FEP.
If you are interested in assuming ownership of a FEP, you can also do this via
pull request. Fork the FEP repository, make your ownership modification, and
submit a pull request. You should mention both the original author and
@TrueCloudLab/architecture-committee or @TrueCloudLab/community-committee in
a comment on the pull request. (If the original author's username is unknown,
use email.) If the original author doesn't respond in a timely manner, the
Committee will make a unilateral decision (it's not like such decisions can't be
reversed 😄).
Committee Responsibilities & Workflow
A FEP editor must be added to the @TrueCloudLab/architecture-committee or
@TrueCloudLab/community-committee group, depending on the relevant FEP types,
and must watch the FEP
repository.
Note that developers with write access to the FEP repository may handle the
tasks that would normally be taken care of by the FEP editors. Alternately, even
developers may request assistance from FEP editors by mentioning the relevant
group.
For each new FEP that comes in an editor does the following:
-
Make sure that the FEP is either co-authored by a Committer, has a Committer as a sponsor, or has a sponsor specifically approved for this FEP by the Committee.
-
Read the FEP to check if it is ready: sound and complete. The ideas must make technical sense, even if they don't seem likely to be accepted.
-
The title should accurately describe the content.
-
The file name extension is correct (i.e.
.md). -
Skim the FEP for obvious defects in language (spelling, grammar, sentence structure, etc.), and code style . Editors may correct problems themselves, but are not required to do so.
-
If a project is portrayed as benefiting from or supporting the FEP, make sure there is some direct indication from the project included to make the support clear. This is to avoid a FEP accidentally portraying a project as supporting a FEP when in fact the support is based on conjecture.
If the FEP isn't ready, an editor will send it back to the author for revision, with specific instructions.
Once the FEP is ready for the repository, a FEP editor will:
-
Assign a FEP number (almost always just the next available number, but sometimes it's a special/joke number, like 666 or 3141).
-
Check that the author has correctly labeled the FEP's type ("Standards Track", "Informational", or "Process"), and marked its status as "Draft".
-
Ensure all CI build and lint checks pass without errors, and there are no obvious issues in the rendered preview output.
-
Merge the new (or updated) FEP.
-
Inform the author of the next steps (open a discussion thread and update the FEP with it, post an announcement, etc).
Updates to existing FEPs should be submitted as a pull request.
Copyright
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.