Added RFC process
This commit is contained in:
Jeremy Borgman
0
docs/0000-template.md
Normal file
0
docs/0000-template.md
Normal file
@@ -30,6 +30,7 @@ Check this nice official documentation from Qt docs as it explains how to transl
|
|||||||
|
|
||||||
## Code
|
## Code
|
||||||
|
|
||||||
|
For small fixes or incremental improvements simply fork the repo and follow the process below. For larger changes submit an [RFC:](RFC.md)
|
||||||
1. [Fork](https://help.github.com/articles/fork-a-repo/) the repository and [clone](https://help.github.com/articles/cloning-a-repository/) your fork.
|
1. [Fork](https://help.github.com/articles/fork-a-repo/) the repository and [clone](https://help.github.com/articles/cloning-a-repository/) your fork.
|
||||||
|
|
||||||
2. Start coding!
|
2. Start coding!
|
||||||
|
|||||||
208
docs/RFC.md
Normal file
208
docs/RFC.md
Normal file
@@ -0,0 +1,208 @@
|
|||||||
|
# Flameshot RFCs
|
||||||
|
|
||||||
|
[Flameshot RFCs]: #flameshot-rfcs
|
||||||
|
|
||||||
|
Many changes, including bug fixes and documentation improvements can be
|
||||||
|
implemented and reviewed via the normal GitHub pull request workflow.
|
||||||
|
|
||||||
|
Some changes though are "substantial", and we ask that these be put through a
|
||||||
|
bit of a design process and produce a consensus among the Flameshot community and development team.
|
||||||
|
|
||||||
|
The "RFC" (request for comments) process is intended to provide a consistent
|
||||||
|
and controlled path for new features to enter the language and standard
|
||||||
|
libraries, so that all stakeholders can be confident about the direction the
|
||||||
|
project is evolving in.
|
||||||
|
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
[Table of Contents]: #table-of-contents
|
||||||
|
|
||||||
|
- [Opening](#flameshot-rfcs)
|
||||||
|
- [Table of Contents]
|
||||||
|
- [When you need to follow this process]
|
||||||
|
- [Before creating an RFC]
|
||||||
|
- [What the process is]
|
||||||
|
- [The RFC life-cycle]
|
||||||
|
- [Reviewing RFCs]
|
||||||
|
- [Implementing an RFC]
|
||||||
|
- [RFC Postponement]
|
||||||
|
- [Help this is all too informal!]
|
||||||
|
|
||||||
|
## When you need to follow this process
|
||||||
|
[When you need to follow this process]: #when-you-need-to-follow-this-process
|
||||||
|
|
||||||
|
You need to follow this process if you intend to make "substantial" changes to
|
||||||
|
flameshot or the RFC process itself. What constitutes a
|
||||||
|
"substantial" change is evolving based on community norms and varies depending
|
||||||
|
on what part of the ecosystem you are proposing to change, but may include the
|
||||||
|
following.
|
||||||
|
|
||||||
|
- Any changes breaking compatibility to command line flags or config files.
|
||||||
|
- Any major changes to the UI
|
||||||
|
- Substantial new features like new tools.
|
||||||
|
|
||||||
|
Some changes do not require an RFC:
|
||||||
|
|
||||||
|
- Rephrasing, reorganizing, refactoring, or otherwise "changing shape does
|
||||||
|
not change meaning".
|
||||||
|
- Improving translations.
|
||||||
|
- Additions that strictly improve objective, numerical quality criteria
|
||||||
|
(warning removal, speedup, better platform coverage, etc.)
|
||||||
|
- Additions only likely to be _noticed by_ other developers-of-flameshot,
|
||||||
|
invisible to users-of-flameshot.
|
||||||
|
|
||||||
|
If you submit a pull request to implement a new feature without going through
|
||||||
|
the RFC process, it may be closed with a polite request to submit an RFC first.
|
||||||
|
|
||||||
|
|
||||||
|
## Before creating an RFC
|
||||||
|
[Before creating an RFC]: #before-creating-an-rfc
|
||||||
|
|
||||||
|
A hastily-proposed RFC can hurt its chances of acceptance. Low quality
|
||||||
|
proposals, proposals for previously-rejected features, or those that don't fit
|
||||||
|
into the near-term roadmap, may be quickly rejected, which can be demotivating
|
||||||
|
for the unprepared contributor. Laying some groundwork ahead of the RFC can
|
||||||
|
make the process smoother.
|
||||||
|
|
||||||
|
Although there is no single way to prepare for submitting an RFC, it is
|
||||||
|
generally a good idea to pursue feedback from other project developers
|
||||||
|
beforehand, to ascertain that the RFC may be desirable; having a consistent
|
||||||
|
impact on the project requires concerted effort toward consensus-building.
|
||||||
|
|
||||||
|
The most common preparations for writing and submitting an RFC include talking
|
||||||
|
the idea over on our [official Slack server](flameshotworkspace.slack.com) or opening an issue on github for discussion.
|
||||||
|
|
||||||
|
|
||||||
|
## What the process is
|
||||||
|
[What the process is]: #what-the-process-is
|
||||||
|
|
||||||
|
In short, to get a major feature added to Flameshot, one must first get the RFC
|
||||||
|
merged into the RFC repository as a markdown file. At that point the RFC is
|
||||||
|
"active" and may be implemented with the goal of eventual inclusion into Flameshot.
|
||||||
|
|
||||||
|
- Fork the Flameshot repo
|
||||||
|
- Copy `docs/0000-template.md` to `docs/RFC/0000-my-feature.md` (where "my-feature" is
|
||||||
|
descriptive). Don't assign an RFC number yet; This is going to be the PR
|
||||||
|
number and we'll rename the file accordingly if the RFC is accepted.
|
||||||
|
- Fill in the RFC. Put care into the details: RFCs that do not present
|
||||||
|
convincing motivation, demonstrate lack of understanding of the design's
|
||||||
|
impact, or are disingenuous about the drawbacks or alternatives tend to
|
||||||
|
be poorly-received.
|
||||||
|
- Submit a pull request. As a pull request the RFC will receive design
|
||||||
|
feedback from the larger community, and the author should be prepared to
|
||||||
|
revise it in response.
|
||||||
|
- Build consensus and integrate feedback. RFCs that have broad support are
|
||||||
|
much more likely to make progress than those that don't receive any
|
||||||
|
comments. Feel free to reach out to the RFC assignee in particular to get
|
||||||
|
help identifying stakeholders and obstacles.
|
||||||
|
- The team will discuss the RFC pull request, as much as possible in the
|
||||||
|
comment thread of the pull request itself. Offline discussion will be
|
||||||
|
summarized on the pull request comment thread.
|
||||||
|
- RFCs rarely go through this process unchanged, especially as alternatives
|
||||||
|
and drawbacks are shown. You can make edits, big and small, to the RFC to
|
||||||
|
clarify or change the design, but make changes as new commits to the pull
|
||||||
|
request, and leave a comment on the pull request explaining your changes.
|
||||||
|
Specifically, do not squash or rebase commits after they are visible on the
|
||||||
|
pull request.
|
||||||
|
- At some point, a member of the development team will propose a "motion for final
|
||||||
|
comment period" (FCP), along with a *disposition* for the RFC (merge, close,
|
||||||
|
or postpone).
|
||||||
|
- This step is taken when enough of the tradeoffs have been discussed that
|
||||||
|
the development is in a position to make a decision. That does not require
|
||||||
|
consensus amongst all participants in the RFC thread (which is usually
|
||||||
|
impossible). However, the argument supporting the disposition on the RFC
|
||||||
|
needs to have already been clearly articulated, and there should not be a
|
||||||
|
strong consensus *against* that position outside of the development team. Team
|
||||||
|
members use their best judgment in taking this step, and the FCP itself
|
||||||
|
ensures there is ample time and notification for stakeholders to push back
|
||||||
|
if it is made prematurely.
|
||||||
|
- In most cases, the FCP period is quiet, and the RFC is either merged or
|
||||||
|
closed. However, sometimes substantial new arguments or ideas are raised,
|
||||||
|
the FCP is canceled, and the RFC goes back into development mode.
|
||||||
|
|
||||||
|
## The RFC life-cycle
|
||||||
|
[The RFC life-cycle]: #the-rfc-life-cycle
|
||||||
|
|
||||||
|
Once an RFC becomes "active" then authors may implement it and submit the
|
||||||
|
feature as a pull request to the Flameshot repo. Being "active" is not a rubber
|
||||||
|
stamp, and in particular still does not mean the feature will ultimately be
|
||||||
|
merged; it does mean that in principle all the major stakeholders have agreed
|
||||||
|
to the feature and are amenable to merging it.
|
||||||
|
|
||||||
|
Furthermore, the fact that a given RFC has been accepted and is "active"
|
||||||
|
implies nothing about what priority is assigned to its implementation, nor does
|
||||||
|
it imply anything about whether a developer has been assigned the task of
|
||||||
|
implementing the feature. While it is not *necessary* that the author of the
|
||||||
|
RFC also write the implementation, it is by far the most effective way to see
|
||||||
|
an RFC through to completion: authors should not expect that other project
|
||||||
|
developers will take on responsibility for implementing their accepted feature.
|
||||||
|
|
||||||
|
Modifications to "active" RFCs can be done in follow-up pull requests. We
|
||||||
|
strive to write each RFC in a manner that it will reflect the final design of
|
||||||
|
the feature; but the nature of the process means that we cannot expect every
|
||||||
|
merged RFC to actually reflect what the end result will be at the time of the
|
||||||
|
next major release.
|
||||||
|
|
||||||
|
In general, once accepted, RFCs should not be substantially changed. Only very
|
||||||
|
minor changes should be submitted as amendments. More substantial changes
|
||||||
|
should be new RFCs, with a note added to the original RFC. Exactly what counts
|
||||||
|
as a "very minor change" is up to the development team.
|
||||||
|
|
||||||
|
|
||||||
|
## Reviewing RFCs
|
||||||
|
[Reviewing RFCs]: #reviewing-rfcs
|
||||||
|
|
||||||
|
While the RFC pull request is up, the development team may schedule meetings with the
|
||||||
|
author and/or relevant stakeholders to discuss the issues in greater detail,
|
||||||
|
and in some cases the topic may be discussed at a sub-team meeting. In either
|
||||||
|
case a summary from the meeting will be posted back to the RFC pull request.
|
||||||
|
|
||||||
|
A sub-team makes final decisions about RFCs after the benefits and drawbacks
|
||||||
|
are well understood. These decisions can be made at any time, but the sub-team
|
||||||
|
will regularly issue decisions. When a decision is made, the RFC pull request
|
||||||
|
will either be merged or closed. In either case, if the reasoning is not clear
|
||||||
|
from the discussion in thread, the sub-team will add a comment describing the
|
||||||
|
rationale for the decision.
|
||||||
|
|
||||||
|
|
||||||
|
## Implementing an RFC
|
||||||
|
[Implementing an RFC]: #implementing-an-rfc
|
||||||
|
|
||||||
|
Some accepted RFCs represent vital features that need to be implemented right
|
||||||
|
away. Other accepted RFCs can represent features that can wait until some
|
||||||
|
arbitrary developer feels like doing the work. Every accepted RFC has an
|
||||||
|
associated issue tracking its implementation in the Flameshot repository; thus that
|
||||||
|
associated issue can be assigned a priority via the triage process that the
|
||||||
|
team uses for all issues in the Flameshot repository.
|
||||||
|
|
||||||
|
The author of an RFC is not obligated to implement it. Of course, the RFC
|
||||||
|
author (like any other developer) is welcome to post an implementation for
|
||||||
|
review after the RFC has been accepted.
|
||||||
|
|
||||||
|
If you are interested in working on the implementation for an "active" RFC, but
|
||||||
|
cannot determine if someone else is already working on it, feel free to ask
|
||||||
|
(e.g. by leaving a comment on the associated issue).
|
||||||
|
|
||||||
|
|
||||||
|
## RFC Postponement
|
||||||
|
[RFC Postponement]: #rfc-postponement
|
||||||
|
|
||||||
|
Some RFC pull requests are tagged with the "postponed" label when they are
|
||||||
|
closed (as part of the rejection process). An RFC closed with "postponed" is
|
||||||
|
marked as such because we want neither to think about evaluating the proposal
|
||||||
|
nor about implementing the described feature until some time in the future, and
|
||||||
|
we believe that we can afford to wait until then to do so.
|
||||||
|
|
||||||
|
Usually an RFC pull request marked as "postponed" has already passed an
|
||||||
|
informal first round of evaluation, namely the round of "do we think we would
|
||||||
|
ever possibly consider making this change, as outlined in the RFC pull request,
|
||||||
|
or some semi-obvious variation of it." (When the answer to the latter question
|
||||||
|
is "no", then the appropriate response is to close the RFC, not postpone it.)
|
||||||
|
|
||||||
|
|
||||||
|
### Help this is all too informal!
|
||||||
|
[Help this is all too informal!]: #help-this-is-all-too-informal
|
||||||
|
|
||||||
|
The process is intended to be as lightweight as reasonable for the present
|
||||||
|
circumstances. As usual, we are trying to let the process be driven by
|
||||||
|
consensus and community norms, not impose more structure than necessary.
|
||||||
Reference in New Issue
Block a user