Summary: Adopt a process for proposing, approving, and tracking major changes to bors-ng.
Motivation
Some of you might remember way back when @khodzha opened a pull request for an E-easy issue, but @Macarse, who had never even realized the issue existed, wasn’t sure if it was a good idea or not. The project leadership (@notriddle) overruled their concerns, mostly because he figured it would be kind of mean to have a newbie open a pull request just to have it rejected with “actually, we didn’t want that anyway”. This essentially indicates a mismatch of expectations: @khodzha and @notriddle thought that the decision had already been made, while @Macarse still thought it was up for debate.
This is not the only time the project leadership ended up making judgement without very much discussion in response to an issue report, pull request, or support thread. Even when there is feedback, it isn’t very organized, and the design decisions that are made there get mixed with support questions, bug reports, and announcements. We need a statement of record about what has been decided and who decided it, and it needs to strike the reasonable balance between “set in stone” and “overridden on the Benevolent Dictator Pro Tempore’s daily whims”. It also needs to maintain the balance between “maintaining a coherent features set and overall vision” and “getting community involvement in decision making”.
Description
In a blatant rip-off of other projects, I propose that we (and I do mean WE, the whole purpose of this exercise is community participation) adopt a lightweight RFC process for making design calls and distinguishing between a proposed change and a planned one.
The project leadership
Throughout this RFC, the project leadership will be a role given a number of responsibilities. In particular, project leadership approves and rejects RFC’s.
Currently, the project leadership is Michael Howell, also known as @notriddle, the Benevolent Dictator Pro Tempore. Future RFC’s are expected to replace him with a team structure, who will act in consensus as the project leadership.
Scope and the Types of RFCs
After this process is put into effect, major changes and events will require RFC’s. These types of RFC’s can be classed as:
- Proposal RFC’s, which include:
- All breaking changes, such as removing or renaming commands, bors.toml configuration options, environment configuration options, changing the name or packaging of the OTP application (which would break people’s deployment scripts), or bumping the Erlang or Elixir version requirement (we will probably make an RFC putting breaking dependency bumps onto some kind of schedule)
- Adding user-visible features, because they need to be tested and maintained to avoid breakage when users relied on them
- Informational RFC’s, which include:
- Starting a talk, meetup, or social networking account that will be expected to officially “represent bors-ng”
- Documenting design issues, deciding to never implement a feature, proposing an experiment, or recording a proof-generated insight
- Process RFC’s, which include:
- Changing the RFC process, the organization of the issue tracker or the support forum, or other community infrastructure
- Amending the Code of Conduct
Major changes do not include:
- Most moderation actions
- Bumping a hex.pm dependency, since the Distillery release process automatically pulls those in anyway
- Refactoring the codebase, even if it’s a refactor that requires lots of churn
- Making a blog post
- Fixing something that is clearly a bug, such as breaking the Not Rocket Science Rule under some edge-case circumstance, crashing, or displaying wrong information
- Minor look and feel improvements, or even minor feature additions to the dashboard that aren’t likely to translate to a we-will-not-break-this commitment
You’re allowed to open an RFC even if it seems like it matches an item on this do-not-include list if there’s some external circumstance that makes it seem important. Worst case scenario we just close it and tell you to “go ahead and implement it”.
Process
The stages
- Pre-RFC: this “pseudo-stage” is not governed by the RFC process, but it is recommended that would-be champions go through one before actually opening an RFC.
- Good ideas to do this include opening a wiki, opening a thread in the Development section of the forum, or discussing it with their coworkers on a corporate chatroom or other non-affiliated space.
- An RFC should have one idea. The project leadership may reject an RFC if it appears too broad.
- Would-be champions should search existing RFC’s before opening a new one.
- RFC Discussion: this is the first actual stage in the process. The responsibilities of all participants are spelled out below this list
- Final comment period: an optional part of the discussion stage, where the discussion is timeboxed at two weeks
- Postponed: project leadership can lock a discussion, either time-boxed or until-further-notice
- Approved: if an RFC is approved, it is assigned a number and its implementation is tracked
- Rejected or Withdrawn: if an RFC is rejected, it does not get a number, but its discussion is preserved
Responsibilities of the champion
The individual (or, I guess, an organization would be allowed to act as a champion as long as they can agree on everything out-of-band before acting together as a hive mind) who opens an RFC up will act as the RFC’s “champion”. They are responsible for defending or editing the RFC based on criticism that comes up during the discussion, acting as the RFC’s advocate.
If the champion no longer wishes to champion the RFC, they can hand it over to someone else (obviously, the new champion and the old champion both have to publicly agree to this) or withdraw the RFC. If the RFC is withdrawn, it will be closed.
For any discussions that happened before the RFC was opened that the champion thinks are relevant, the champion should copy any knowledge they created into the RFC or the discussion thread. They should also copy any necessary knowledge from the RFC’s own discussion thread into the RFC, so that the RFC’s text can stand alone. Linking to external discussions is allowed, but they should copy or summarize it in case the third-party discussion host goes away.
For an RFC to be accepted it must meet certain minimum criteria. It must not be too broad. It must be a clear and complete description of the proposal. The enhancement must represent a net improvement. The RFC must be proven possible, either by having already implemented it, simulated it, or by including analyses or an argument. The RFC should also summarize the rationale behind the change.
Responsibilities of the project leadership
While anyone can participate in the RFC discussion, the final decision about approving or rejecting an RFC lies with the project leadership (and the mod team, if they decide that an “RFC” is pure spam they can just reject it, but the mod team can’t just accept an RFC). They do not have to put it up to a community vote, though they will need to come to an internal consensus, and they may ask for a non-binding poll if they think it would help.
The project leadership is expected to voice their concerns, allowing the champion to edit or defend the RFC. As described in the Code of Conduct, the project leadership shall make every effort to maintain a professional atmosphere, and to make the champion feel that they are being helped, not hindered. The win condition is one where everyone involved feels that they made the best possible decision with what they have.
Project leadership must put an RFC into a “Final Comment Period” if they wish to accept it, and may (but need not) do so if they wish to reject it. Final Comment Period lasts two weeks, to make sure that anyone who receives RFC’s in weekly digests has a chance to respond. After FCP, all non-staff commenting is disabled and project leadership must make their final decision, moving the RFC from the discussion phase on to the accepted or rejected category, and assigning it a number if they accepted it.
Responsibilities for all discussion participants
The most important rule is to keep tabs on the discussion, and avoid relitigating a point that has already been made. As always, follow the Code of Conduct.
It is highly recommended that third-party participants avoid acting as the devil’s advocate. Instead, please represent what your actually needs are in an honest way; the personal experience of individuals who are not the champion or a member of the project is the most valuable contribution that third-party participants can make.
Also, participants should send any mechanical corrections (spelling, grammar, formatting) to the champion as a Private Message, not as a public post in the thread. The project leadership appreciates mechanical fixes, and the champion probably does too, but once they’ve been fixed any post that corrects them is just clutter, not something that people who want to understand what happened should have to read through years later.
How the discussion system should work
The process overview given below is intentionally a God’s-Eye-View, with no consideration for how it will be implemented from a technical perspective. Before converting this pre-RFC into the final RFC-0001, this section “How the discussion system should work” should be replaced with a section “How to open an RFC”, documenting how the chosen system works. Anyone who proposes to build a new system from scratch must make a credible commitment to write and maintain the system themselves.
The discussion system for RFC’s must support the following:
- Separate discussion threads for each RFC
- Tagging, to mark an RFC with its stage
- Thread locking
- The “final comment period” mechanic, where a thread is automatically locked after two weeks
- The time-boxed locking would be nice, for postponing an RFC until a set time, but is not mandatory
- Some sort of editable document for the RFC’s text, with change tracking
- Public readability
- Accessibility with a web browser
- A documented API, so that further conveniences can be added over time
- Persistence
- Google must be able to index the RFC text
While it’s not required for the MVP version of the RFC process, we would very much benefit from a Kanban Board of all the RFCs. I’m imagining something that looks like this:
| Discussion | Final Comment Period | Approved | Implemented | Rejected/Withdrawn | Postponed |
|---|---|---|---|---|---|
|
Write Status to a GitHub Check Minimally-Viable GitLab Support New-Style Emoji Non-Batching Mode |
Batch-Size Limit |
Localization Support for the Web Site GitLab Worker Protocol Basic REST API |
Try Cancellation Command ( |
Vape spam Turn bors into a SPA Full-blown issue tracking |
These examples are not intended to say anything about whether the example text is appropriate or not. Except the vape spam; obviously when anything like that shows up in the RFC discussion system, it’ll be rejected.
If it doesn’t have built-in support for that Kanban board, which it probably doesn’t if it’s not custom-built, it should be possible to build it on top of the API.
Drawbacks
So far, I’ve basically copied what Rust does, with a couple of tweaks to fit Bors’s slower development pace and a few notes and bits pulled from Swift Evolution, BEP, and PEP.
This means we’re already very familiar with the major drawbacks:
- Public RFC’s have been known to attract a lot of attention, sometimes creating a discussion that is so long that it’s impossible to read it all, which compounds the problem because it causes people to post the same concern twice.
- Public RFC’s also attract concern trolls, since they have so much attention paid to them, making the length problem even worse.
- Settling on a single canonical discussion medium requires one to make final decisions about a bunch of trade-offs, such as ease of archive (the contents of a git repository excel at this one), moderation tools (Discourse excels at this one), familiarity (GitHub Issues excel at this one), ease of entry (chat rooms excel at this one), sophisticated review features (reviewable.io and Gerrit excel at this one), and others that I can’t think of right off the bat. The disorganized status quo allows participants to make an in-the-moment best call.
What happens now?
This is a proposed text for RFC-0001, minus the parts that will eventually be added that are platform-specific. We need to discuss the RFC process first, then decide on what the best platform is for it, then we can finally put the RFC process into effect.
