potyarkin/frostfs.info
1
0
Fork 0
forked from TrueCloudLab/frostfs.info
Code Pull requests Activity

[#12] Reflect GitHub → Forgejo move in FEPs

Browse source 
Signed-off-by: Stanislav Bogatyrev <s.bogatyrev@yadro.com>
This commit is contained in:
Stanislav Bogatyrev 2023-04-07 15:11:50 +03:00
parent 4f5671d619
commit 1949e48d45
1 changed files with 54 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

114
content/proposals/proc/FEP-0001.md
View file

@ -2,10 +2,12 @@
FEP: 1 FEP: 1
Title: FEP Purpose and Guidelines Title: FEP Purpose and Guidelines
Author: Stanislav Bogatyrev <realloc@realloc.spb.ru> Author: Stanislav Bogatyrev <realloc@realloc.spb.ru>
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 Status: Draft
Type: Process Type: Process
Date: 2023-02-01 Date: 2023-04-17
--- ---
### What is a FEP? ### 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 Because the FEPs are maintained as text files in a versioned repository, their
revision history is the historical record of the feature proposal. This revision history is the historical record of the feature proposal. This
historical record is available by the normal git commands for retrieving older historical record is available by the normal git commands for retrieving older
revisions, and can also be browsed on GitHub in [frostfs.info revisions, and can also be browsed in [frostfs.info
repository](https://github.com/TrueCloudLab/frostfs.info/tree/master/content/proposals). repository](https://git.frostfs.info/TrueCloudLab/frostfs.info/src/branch/master/content/proposals).
The current rendered version is available on [frostfs.info The current rendered version is available on [frostfs.info
site](https://frostfs.info/proposals/). 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 consensus; unlike Informational FEPs, they are more than recommendations, and
community members are typically not free to ignore them. Examples include community members are typically not free to ignore them. Examples include
procedures, guidelines, changes to the decision-making process, and changes 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 ### FEP Workflow
@ -79,18 +81,18 @@ Governance).
The FEP process begins with a new idea for the FrostFS stack. It is highly 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 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 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 tracker for the corresponding repository. The Architecture Committee reserves
the right to reject FEP proposals if they appear too unfocused or too broad. If 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. 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 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 format described below, shepherds the discussions in the appropriate issues or
issues or chats, and attempts to build community consensus around the idea. The chats, and attempts to build community consensus around the idea. The FEP author
FEP author should first attempt to ascertain whether the idea is feasible for should first attempt to ascertain whether the idea is feasible for the new FEP.
the new FEP. Creating an issue in appropriate GitHub repository with 'idea' or Creating an issue in appropriate repository with 'idea' or 'discussion' label is
'discussion' label is usually the best way to go about this, unless a more usually the best way to go about this, unless a more specialized venue is
specialized venue is appropriate. appropriate.
Vetting an idea publicly before going as far as writing a FEP is meant to save 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 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 Ideally, a Committer sponsor is identified, but non-Committer sponsors may also
be selected with the approval of the Architecture Committee. Members of the be selected with the approval of the Architecture Committee. Members of the
GitHub "Committers" and "Architecture Committee" teams are pre-approved to be "Committers" and "Architecture Committee" teams are pre-approved to be sponsors.
sponsors. The sponsor's job is to provide guidance to the FEP author to help The sponsor's job is to provide guidance to the FEP author to help them through
them through the logistics of the FEP process (somewhat acting like a mentor). the logistics of the FEP process (somewhat acting like a mentor). Being a
Being a sponsor does **not** disqualify that person from becoming a co-author. sponsor does **not** disqualify that person from becoming a co-author. The
The sponsor of a FEP is recorded in the "Sponsor:" field of the header. 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 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 ready for submission, the proposal should be submitted as a draft FEP via a
[GitHub pull request in frostfs.info [Pull request in frostfs.info
repository](https://github.com/TrueCloudLab/frostfs.info/pulls). The draft must 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 be written in FEP style as described below, else it will fail review immediately
(although minor errors may be corrected by the editors). (although minor errors may be corrected by the editors).
The standard FEP workflow is: The standard FEP workflow is:
* You, the FEP author, fork the [frostfs.info * 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/<type>/fep-X.md` that contains your new FEP. Use "X" named `content/proposals/<type>/fep-X.md` that contains your new FEP. Use "X"
as your draft FEP number. as your draft FEP number.
@ -142,11 +144,7 @@ The standard FEP workflow is:
field enter "Draft". For full details, see [FEP Header Preamble]({{<ref field enter "Draft". For full details, see [FEP Header Preamble]({{<ref
"#fep_header_preamble">}}). "#fep_header_preamble">}}).
* Update `.github/CODEOWNERS` such that any co-author(s) or sponsors with write * Push this to your git repository fork and submit a pull request.
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.
* The FEP editors review your PR for structure, formatting, and other * The FEP editors review your PR for structure, formatting, and other
errors. Approval criteria are: errors. Approval criteria are:
@ -160,15 +158,14 @@ The standard FEP workflow is:
Editors are generally quite lenient about this initial review, expecting that Editors are generally quite lenient about this initial review, expecting that
problems will be corrected by the reviewing process. problems will be corrected by the reviewing process.
**Note:** Approval of the FEP is no guarantee that there are no embarrassing **Note:** Approval of the FEP is no guarantee that there are no embarrassing
mistakes! Correctness is the responsibility of authors and reviewers, not the mistakes! Correctness is the responsibility of authors and reviewers, not the
editors. editors.
If the FEP isn't ready for approval, an editor will send it back to the author 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 for revision, with specific instructions, using pull requests mechanism.
mechanism.
* Once approved, Architecture Committee will assign your FEP a number. * Once approved, Architecture Committee will assign your FEP a number.
Once the review process is complete, and the FEP editors approve it (note that 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 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 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 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 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 its proposed specification, a new issue should typically be created to solicit
solicit additional feedback. If this occurs, the ``Discussions-To`` link must be additional feedback. If this occurs, the ``Discussions-To`` link must be updated
updated and a new ``Post-History`` entry added pointing to this new thread. and a new ``Post-History`` entry added pointing to this new thread.
FEP authors are responsible for collecting community feedback on a FEP before FEP authors are responsible for collecting community feedback on a FEP before
submitting it for review. However, to avoid long-winded and open-ended 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. be considered. FEP authors should use their discretion here.
Once the FEP is assigned a number and committed to the FEP repository, Once the FEP is assigned a number and committed to the FEP repository,
substantive issues should generally be discussed in corresponding GitHub pull substantive issues should generally be discussed in corresponding pull request
request reviews or issues. This ensures everyone can follow and contribute, reviews or issues. This ensures everyone can follow and contribute, avoids
avoids fragmenting the discussion, and makes sure it is fully considered as part fragmenting the discussion, and makes sure it is fully considered as part of the
of the FEP review process. Comments, support, concerns and other feedback on FEP review process. Comments, support, concerns and other feedback on this
this designated thread are a critical part of what the Architecture Committee or designated thread are a critical part of what the Architecture Committee or
FEP-Delegate will consider when reviewing the FEP. FEP-Delegate will consider when reviewing the FEP.
#### FEP Review & Resolution #### FEP Review & Resolution
@ -428,9 +425,9 @@ Each FEP must begin with an RFC-2822 style preamble in [Hugo page level
* Superseded-By: <fep number> * Superseded-By: <fep number>
``` ```
The Author header lists the names, and optionally the email addresses of GitHub The Author header lists the names, and optionally the email addresses or
handles of all the authors/owners of the FEP. The format of the Author header GitHub/Codeberg/TrueCloudab Forgejo handles of all the authors/owners of the
values must be: FEP. The format of the Author header values must be:
```YAML ```YAML
Random J. User <random@example.com> Random J. User <random@example.com>
@ -459,9 +456,9 @@ is a Committer then no sponsor is necessary and thus this field should be left
out. out.
The Discussions-To header provides the URL to the relevant discussion thread for 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 the FEP. Normally an issue or Pull Request. For email lists, this should be a
be a direct link to the thread in the list's archives, rather than just a direct link to the thread in the list's archives, rather than just a mailto: or
mailto: or hyperlink to the list itself. hyperlink to the list itself.
The Type header specifies the type of FEP: Standards Track, Informational, or The Type header specifies the type of FEP: Standards Track, Informational, or
Process. 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 discretion of the authors, until submitted to the corresponding Committee for
review and resolution. Substantive content changes should generally be first review and resolution. Substantive content changes should generally be first
proposed on the FEP's discussion thread listed in its `Discussions-To` header, 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 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]({{<ref modifying other FEPs, consult the [FEP Maintenance]({{<ref
"#fep_maintenance">}}) section. "#fep_maintenance">}}) section.
See the [Contributing 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 for additional details, and when in doubt, please check first with the FEP
author and/or a FEP editor. 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 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 pull request. Fork the FEP repository, make your ownership modification, and
submit a pull request. You should mention both the original author and submit a pull request. You should mention both the original author and
`@TrueCloudLab/architecture-committee` or `@TrueCloudLab/community-committee` in a `@TrueCloudLab/architecture-committee` or `@TrueCloudLab/community-committee` in
comment on the pull request. (If the original author's GitHub username is a comment on the pull request. (If the original author's username is unknown,
unknown, use email.) If the original author doesn't respond in a timely manner, use email.) If the original author doesn't respond in a timely manner, the
the Committee will make a unilateral decision (it's not like such decisions Committee will make a unilateral decision (it's not like such decisions can't be
can't be reversed :smile:. reversed :smile:).
### Committee Responsibilities & Workflow ### Committee Responsibilities & Workflow
A FEP editor must be added to the `@TrueCloudLab/architecture-committee` or A FEP editor must be added to the `@TrueCloudLab/architecture-committee` or
`@TrueCloudLab/community-committee` group on GitHub, depending on the relevant `@TrueCloudLab/community-committee` group, depending on the relevant FEP types,
FEP types, and must watch the [FEP and must watch the [FEP
repository](https://github.com/TrueCloudLab/frostfs.info). repository](https://git.frostfs.info/TrueCloudLab/frostfs.info).
Note that developers with write access to the `FEP repository` may handle the 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 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 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: 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`). * 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 * Skim the FEP for obvious defects in language (spelling, grammar, sentence
structure, etc.), and code style . Editors may correct problems themselves, structure, etc.), and code style . Editors may correct problems themselves,
but are not required to do so. 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 * Inform the author of the next steps (open a discussion thread and
update the FEP with it, post an announcement, etc). 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 ### Copyright