mirror of https://github.com/hyprwm/RFCs.git
296 lines
14 KiB
Markdown
296 lines
14 KiB
Markdown
# HyprWM RFCs (Request for Comments)
|
|
|
|
Welcome to the RFC (Request for Comments) repository for HyprWM. Here you may
|
|
propose, discuss and track changes to various aspects of the HyprWM organization
|
|
including, but not limited to, community structure, project features, packaging
|
|
and security of projects.
|
|
|
|
## What is an RFC?
|
|
|
|
RFC stands for Request for Comments. It's a formalized way to propose
|
|
significant changes, new features, or enhancements to a project. The purpose of
|
|
an RFC is to solicit feedback and build consensus around proposed changes before
|
|
they are implemented.
|
|
|
|
## Motivation
|
|
|
|
The purpose of the RFC process is to provide a structured and collaborative
|
|
process for proposing and discussing significant changes, new feature additions
|
|
or enhancements to HyprWM projects. By implementing and normalizing the RFC
|
|
process, we aim to:
|
|
|
|
- Encourage participation: Provide a platform for all community members to
|
|
contribute ideas and feedback.
|
|
- Foster consensus: Facilitate discussions to build agreement and alignment
|
|
around proposed changes before they are implemented.
|
|
- Improve transparency: Document proposals, discussions, and decisions to keep
|
|
the community informed about the direction of HyprWM projects.
|
|
- Enhance quality: Ensure that proposed changes undergo proper review and
|
|
consideration alongside healthy communication before implementation, hopefully
|
|
leading to higher-quality outcomes than hastily done merges.
|
|
|
|
RFC documents are intended as the permanent documentation of a decision and a
|
|
snapshot of a moment in time, rather than a specification-like normative
|
|
document. The goal of the RFC process is to concentrate relevant discussion in
|
|
one location that can be easily archived and viewed.
|
|
|
|
## When this process is followed
|
|
|
|
The RFC process is followed when one intends to propose large changes to
|
|
projects under the HyprWM umbrella. The "large changes" in question may be
|
|
redefined in time, as the community evolves, but for the time being the
|
|
following are included:
|
|
|
|
- Broad changes to the documentation
|
|
- Semantic or syntactic changes to, e.g., Hyprlang
|
|
- Large restructures of the community mediums (Discord, Matrix, ...)
|
|
- Nix tooling and packaging
|
|
- Expansions of the scope of HyprWM (new projects, packaging, ...)
|
|
- Introduction of new interfaces to existing projects
|
|
|
|
Certain topics of interest, regardless of how many RFCs are submitted, will not
|
|
be subject to change:
|
|
|
|
- The project language (C++)
|
|
- The project owner ([@vaxerski](https://github.com/vaxerski))
|
|
|
|
Other changes, while difficult, may be subject to change if a compelling
|
|
argument is made:
|
|
|
|
- Build system (CMake)
|
|
- Wiki software
|
|
- Code style
|
|
|
|
## Glossary
|
|
|
|
### RFC Steering Committee
|
|
|
|
A group of members assigned by the
|
|
[Core HyprWM Team](https://github.com/orgs/hyprwm/teams/core) which would stay
|
|
consistent until the team composition is potentially changed through an RFC
|
|
proposal. This committee is tasked with forming an RFC Shepherd team from the
|
|
available nominations on each new RFC. The responsibilities of this team also
|
|
include naming a "leader" for the shepherd team during its life-cycle. This
|
|
**must** happen within 2 weeks after the Pull Request to the RFCs repository has
|
|
been opened. Until a leader has been assigned, the Steering Committee will also
|
|
be held responsible for guiding all discussions under the relevant pull request.
|
|
|
|
In case of the Shepherding Team not doing its work as expected, the Steering
|
|
Committee shall encourage them [to do so] or step in to assign a new Shepherd
|
|
team that may or may not include previous teams. They will also be in charge of
|
|
marking the end of an RFC discussion period (i.e. merging or rejecting) the RFC.
|
|
|
|
Current RFC Steering Committee consists of:
|
|
|
|
- TBD
|
|
- TBD
|
|
- TBD
|
|
- ...
|
|
|
|
### Shepherd Team
|
|
|
|
A team of 2-4 community members, defined unanimously by the RFC Steering
|
|
Committee, tasked with marking the end of an RFC's life-cycle by marking it for
|
|
either merge or rejection. This team is formed during each RFC's life-cycle, and
|
|
for the relevant RFC only from community members nominated in the discussion of
|
|
that RFC.
|
|
|
|
This team shall be people who are very familiar with the components that are the
|
|
main subjects of the RFC, and the author may not be a part of the Shepherd Team.
|
|
In addition to the previous restrictions, at least one and at most half of the
|
|
Shepherd Team shall be part of the RFC Steering Committee.
|
|
|
|
The responsibility of the team is to guide and moderate the discussion as long
|
|
as it is constructive, brings new points to the table and while the RFC is
|
|
iterated and circled-back to from time to time. If this is no longer the case,
|
|
the Shepherd Team shall decide on whether to proceed with the FCP.
|
|
|
|
#### Shepherd Leader
|
|
|
|
The Shepherd Leader refers to the person in charge of the RFC process for a
|
|
specific RFC, with the responsibility of ensuring that the process is followed
|
|
in a neat, timely and civil fashion. This person has no special responsibility
|
|
with regard to moving an undecided Shepherd Team to a certain decision.
|
|
|
|
### Final Comment Period (FCP)
|
|
|
|
A period of 8 calendar days, which will be called by the Shepherd Team after the
|
|
RFC has received the proper amount of discussion appropriate to the size of the
|
|
RFC, and enough of the pros and cons of said RFC have been discussed. The
|
|
Shepherd Team will propose to either accept, or reject the RFC once the FCP
|
|
period is concluded.
|
|
|
|
## Process from Creation to Merge
|
|
|
|
_In short, to get a major change propagated to the HyprWM organization or to a
|
|
project under the HyprWM organization, one must first get an RFC merged into the
|
|
RFC repository as a markdown file under the `rfcs` directory, with the file name
|
|
`XXXX-<name>.md` where the `XXXX` in the name stands for the RFC number,
|
|
starting from `0000`. A template is available in the root of this repository. At
|
|
that point the RFC is accepted, and may be implemented with the goal of eventual
|
|
inclusion into HyprWM or a project under the HyprWM organization._
|
|
|
|
<div align="center">
|
|
<img src="./assets/rfc-process.png" alt="RFC Process">
|
|
</div>
|
|
|
|
1. Have a cool idea!
|
|
2. Fill in the RFC. Put good care into details: RFCs that do not present
|
|
convincing motivation, demonstrate understanding of the impact of proposed
|
|
change or are disingenuous about the drawbacks or alternatives may be poorly
|
|
received, or vetoed.
|
|
3. In case your RFC is a technical proposal, consider preparing a prototype that
|
|
visualizes your idea for potential shepherd and bystanders. It will also help
|
|
you catch any pitfalls your idea might have stumbled upon.
|
|
4. Submit a pull request. The RFC will receive feedback on its design and
|
|
implementation from the larger community, therefore the author must be
|
|
prepared to amend and revise if necessary.
|
|
5. For the nomination process for potential members of the RFC Shepherd Team
|
|
that is exclusive to each RFC, anyone interested can either nominate another
|
|
person who is willing or themselves to be a potential member of the RFC
|
|
Shepherd team. This can already be done when submitting the PR, with a
|
|
pre-formed Shepherd team.
|
|
6. The RFC Steering Committee assigns a subset of nominees to the RFC Shepherd
|
|
Team and assigns a designated leader to it. This has to be done unanimously,
|
|
and is considered a blocker. The RFC may be on hold until a leader is
|
|
assigned.
|
|
7. Consensus is built, and potential feedback is received by the RFC author.
|
|
RFCs that have broad support and consensus are much more likely to make
|
|
forward progress than those that do not receive any comments. Do feel free to
|
|
reach out to the RFC Shepherd Team leader in particular to get help
|
|
identifying stakeholders and obstacles.
|
|
8. The RFC Shepherd team will discuss the RFC pull request, as much as possible
|
|
in the comment thread of the pull request for the relevant RFC. Discussion
|
|
outside the pull request, either offline or in a video conference, that might
|
|
be preferable to get to a solution for complex issues, must be summarized by
|
|
the participants of said discussions in the pull request comment thread.
|
|
9. RFCs rarely go through without any changes, especially as alternatives and
|
|
drawbacks are pointed out. You may make edits, big or small, to the RFC in
|
|
order to clarify or change the proposed design. However, changes must be made
|
|
as new commits to the pull request, actively avoiding force pushes. On each
|
|
commit, leave a comment explaining your changes and your motivation for them.
|
|
Do not squash or rebase commits after they have been made visible once on the
|
|
pull request.
|
|
10. At some point, a member of the RFC Shepherd Team will propose to start the
|
|
"Final Comment Period" (FCP) on behalf of the team, along with a proposed
|
|
disposition for the RFC. This is usually one of "merge" or "close", and the
|
|
final decision is forwarded to the members of the Core Team who will either
|
|
**veto** the decision, or carry it out according to previous discussion.
|
|
|
|
- This step is taken when enough of the trade-offs and pitfalls have been
|
|
discussed that the RFC Shepherd team is in an appropriate position to make
|
|
a final decision. That does not require consensus amongst all participants
|
|
in the RFC thread (which is usually impossible). However, the argument
|
|
supporting the resulting disposition on the RFC needs to have already been
|
|
clearly articulated, and there should not be a strong consensus against
|
|
that position outside the RFC Shepherd Team. The RFC Shepherd Team members
|
|
are to use their best judgement in taking this steep, and the FCP itself
|
|
ensures there is ample time and notification for stakeholders to push back
|
|
if it is made prematurely.
|
|
|
|
- For RFCs with lengthy discussion, the motion to FCP is usually preceded by
|
|
a summary comment trying to lay out the current state of the discussion
|
|
and major trade-offs/points of disagreement.
|
|
|
|
- In order to actually enter FCP, it must be made clear that all members of
|
|
the RFC Shepherd team sign off the motion, e.g. through commits or
|
|
approvals, or a meeting protocol that has been recorded or transcribed.
|
|
|
|
11. The FCP is advertised widely by the Shepherds, most importantly on
|
|
officially endorsed social channels (e.g. Discord or Matrix). It lasts 8
|
|
calendar days starting with the announcement on the Pull Request (and the
|
|
subsequent Discord/Matrix announcement), so that it is open for at least 5
|
|
business days. This way, all stakeholders and community members a have a
|
|
chance to raise any final objections before a decision is reached.
|
|
12. In case of acceptance, the RFC Steering Committee merges the PR. Otherwise,
|
|
the RFC's pull request is closed by a Core Team member. If no consensus can
|
|
be reached on the RFC, but the idea in general is accepted, it gets closed,
|
|
too. A note is added that it should be proposed again, when the
|
|
circumstances that are preventing the discussion from coming to another
|
|
decision change.
|
|
13. If the RFC has been accepted, but a veto right is exercised by a Core Team
|
|
member, the RFC is invited to revise or to be resubmitted in the future by
|
|
the Core Team member. However, if the Core Team member thinks the interests
|
|
of HyprWM and the RFC author misalign, the RFC may be closed outright as per
|
|
the veto privilege.
|
|
|
|
<!--
|
|
Borrowed from https://github.com/NixOS/rfcs - It is modified to include the
|
|
veto process as well as other unhappy conditions.
|
|
|
|
This diagram is available under the CC-BY-SA 4.0 License as indicated
|
|
by the license section. Please see:
|
|
<https://github.com/NixOS/rfcs/?tab=readme-ov-file#license>
|
|
-->
|
|
<div align="center">
|
|
<img src="./assets/rfc-lifecycle.png" alt="RFC Life-cycle">
|
|
</div>
|
|
|
|
## Unhappy Cases
|
|
|
|
Ideally every RFC will complete review and be accepted or rejected.
|
|
Unfortunately, this can not always be the case. Below are the "Unhappy Cases" in
|
|
which your RFC will be held back, or closed.
|
|
|
|
### On Hold
|
|
|
|
If the author is unable or unwilling to update the RFC in a timely fashion they
|
|
may mark an RFC as "On Hold" to indicate that the RFC should not continue to be
|
|
pushed forward for the time being.
|
|
|
|
### Can't Find Shepherds
|
|
|
|
If an RFC that meet all prior conditions to move forward, but cannot establish a
|
|
team of members willing to Shepherd the RFC discussion (i.e. a Shepherd Team)
|
|
then the RFC will be put on hold for 30 days with the following message:
|
|
|
|
```
|
|
This RFC has acquired insufficient interest from the community. [A full
|
|
shepherd team is mandatory](https://github.com/hyprwm/RFCs/#shepherd-team)
|
|
for a RFC to move foward.
|
|
|
|
If not enough shepherds are found within the next month, this RFC will be closed
|
|
until enough participantss are found. The PR can be reopened at anytime if
|
|
enough shepherd nominations are made.
|
|
|
|
[Read more about the RFC process here](https://github.com/hyprwm/RFCs/blob/master/README.md)
|
|
```
|
|
|
|
If another month, starting from the sending of this message, passes and an RFC
|
|
team has not yet been formed, the pull request for the RFC will be closed with
|
|
the following message:
|
|
|
|
```
|
|
This RFC is being closed due to lack interest. If enough shepherds are found this
|
|
issue can be reopened. [Read more about the RFC process
|
|
here](https://github.com/hyprwm/RFCs/blob/master/README.md)
|
|
```
|
|
|
|
## The RFC life-cycle
|
|
|
|
Most RFCs describe changes that eventually need to be implemented, usually but
|
|
not necessarily in the form of a series of pull requests to one of the
|
|
repositories under the HyprWM organization. Ideally, an implementation or a
|
|
demonstration accompanies the initial RFC pull request when it is made. If
|
|
neither are present, the RFC author shall include a "roadmap" that describes the
|
|
order in which proposed changes will happen.
|
|
|
|
An RFC being marked as accepted shall not be seen as a rubber stamp, and in
|
|
particular still does not mean that the proposed changes will be made; it does
|
|
mean, however, in principle that all the major stakeholders have agreed to the
|
|
feature and are amenable to proceeding forward with it. In general though, the
|
|
"accepted" status means that the proposed changes are to be followed through
|
|
unless there are no substantial technical objections, or a veto from one of the
|
|
Core Team members.
|
|
|
|
It should be noted that the fact a given RFC has been accepted implies nothing
|
|
about what priority shall be assigned to its implementation unless that has been
|
|
explicitly stated in the RFC, and has been accepted by consensus. Authors shall
|
|
not expect that other project developers or team members will take on the
|
|
responsibility for implementing proposed changes.
|
|
|
|
## License
|
|
|
|
All contributions are licensed by their respective authors under the
|
|
[CC-BY-SA 4.0 License](https://creativecommons.org/licenses/by-sa/4.0/legalcode).
|