forked from TrueCloudLab/frostfs.info
[#12] Reflect GitHub → Forgejo move in FEPs
Signed-off-by: Stanislav Bogatyrev <s.bogatyrev@yadro.com>
This commit is contained in:
parent
4f5671d619
commit
1949e48d45
1 changed files with 54 additions and 60 deletions
|
|
@ -2,10 +2,12 @@
|
|||
FEP: 1
|
||||
Title: FEP Purpose and Guidelines
|
||||
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
|
||||
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/<type>/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]({{<ref
|
||||
"#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: <fep number>
|
||||
```
|
||||
|
||||
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 <random@example.com>
|
||||
|
|
@ -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]({{<ref
|
||||
"#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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue