diff --git a/content/proposals/proc/FEP-0001.md b/content/proposals/proc/FEP-0001.md index 012530f..730a8d0 100644 --- a/content/proposals/proc/FEP-0001.md +++ b/content/proposals/proc/FEP-0001.md @@ -2,10 +2,12 @@ FEP: 1 Title: FEP Purpose and Guidelines Author: Stanislav Bogatyrev -Discussions-To: https://github.com/TrueCloudLab/frostfs.info/pull/3 +Discussions-To: + - https://git.frostfs.info/TrueCloudLab/frostfs.info/pulls/12 + - https://github.com/TrueCloudLab/frostfs.info/pull/3 Status: Draft Type: Process -Date: 2023-02-01 +Date: 2023-04-17 --- ### What is a FEP? @@ -27,8 +29,8 @@ 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 on GitHub in [frostfs.info -repository](https://github.com/TrueCloudLab/frostfs.info/tree/master/content/proposals). +revisions, and can also be browsed in [frostfs.info +repository](https://git.frostfs.info/TrueCloudLab/frostfs.info/src/branch/master/content/proposals). The current rendered version is available on [frostfs.info site](https://frostfs.info/proposals/). @@ -65,7 +67,7 @@ There are three kinds of FEP: 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. + to the tools or environment used in FrostFS development. ### FEP Workflow @@ -79,18 +81,18 @@ 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 GitHub issue +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 GitHub -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 GitHub repository with 'idea' or -'discussion' label is usually the best way to go about this, unless a more -specialized venue is appropriate. +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 @@ -117,23 +119,23 @@ 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 -GitHub "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. +"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 -[GitHub pull request in frostfs.info -repository](https://github.com/TrueCloudLab/frostfs.info/pulls). The draft must +[Pull request in frostfs.info +repository](https://git.frostfs.info/TrueCloudLab/frostfs.info/pulls). 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](https://github.com/TrueCloudLab/frostfs.info/), and create a file + repository](https://git.frostfs.info/TrueCloudLab/frostfs.info/), and create a file named `content/proposals//fep-X.md` that contains your new FEP. Use "X" as your draft FEP number. @@ -142,11 +144,7 @@ The standard FEP workflow is: field enter "Draft". For full details, see [FEP Header Preamble]({{}}). -* Update `.github/CODEOWNERS` such that any co-author(s) or sponsors with write - access to the repository are listed for your new file. This ensures any future - pull requests changing the file will be assigned to them. - -* Push this to your GitHub fork and submit a pull request. +* 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: @@ -160,15 +158,14 @@ The standard FEP workflow is: 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 GitHub pull requests - mechanism. - + 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 @@ -198,12 +195,12 @@ 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 on GitHub. +issue or Pull Request. If a FEP undergoes a significant re-write or other major, substantive changes to -its proposed specification, a new GitHub 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. +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 @@ -214,11 +211,11 @@ 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 GitHub 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 +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 @@ -428,9 +425,9 @@ Each FEP must begin with an RFC-2822 style preamble in [Hugo page level * Superseded-By: ``` -The Author header lists the names, and optionally the email addresses of GitHub -handles of all the authors/owners of the FEP. The format of the Author header -values must be: +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: ```YAML Random J. User @@ -459,9 +456,9 @@ 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 a GitHub 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 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. @@ -489,14 +486,14 @@ 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 a GitHub issue or Pull +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 GitHub PR to submit their changes. For guidance on +themselves by using a PR to submit their changes. For guidance on modifying other FEPs, consult the [FEP Maintenance]({{}}) section. See the [Contributing -Guide](https://github.com/TrueCloudLab/frostfs.info/blob/master/CONTRIBUTING.md) +Guide](https://git.frostfs.info/TrueCloudLab/frostfs.info/blob/master/CONTRIBUTING.md) for additional details, and when in doubt, please check first with the FEP author and/or a FEP editor. @@ -516,23 +513,23 @@ 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 GitHub 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 :smile:. +`@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 :smile:). ### Committee Responsibilities & Workflow A FEP editor must be added to the `@TrueCloudLab/architecture-committee` or -`@TrueCloudLab/community-committee` group on GitHub, depending on the relevant -FEP types, and must watch the [FEP -repository](https://github.com/TrueCloudLab/frostfs.info). +`@TrueCloudLab/community-committee` group, depending on the relevant FEP types, +and must watch the [FEP +repository](https://git.frostfs.info/TrueCloudLab/frostfs.info). 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 on GitHub. +group. For each new FEP that comes in an editor does the following: @@ -547,9 +544,6 @@ For each new FEP that comes in an editor does the following: * The file name extension is correct (i.e. `.md`). -* Ensure that everyone listed as a sponsor or co-author of the FEP who has write - access to the FEP repository is added to `.github/CODEOWNERS`. - * 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. @@ -579,7 +573,7 @@ Once the FEP is ready for the repository, a FEP editor will: * 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 GitHub pull request. +Updates to existing FEPs should be submitted as a pull request. ### Copyright