Skip to content

chore: Add RFC process #1961

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Mar 5, 2020
Merged

chore: Add RFC process #1961

merged 4 commits into from
Mar 5, 2020

Conversation

binarylogic
Copy link
Contributor

@binarylogic binarylogic commented Mar 1, 2020

Problem

Something that has been bothering me lately is our RFC process. Up until recently (~3 months ago) changes have been mostly isolated and green-field. Discussions were less necessary and simple specifications within issues were sufficient. This was on purpose, as we should strive to reduce the process as much as possible.

Lately, though, changes have required more discussion due to:

  1. Vector is becoming more mature, there are more moving parts.
  2. Changes are exposing larger design questions.
  3. Changes are intermingled and sometimes overlap or block each other.
  4. We have subject matter experts on various parts of Vector that should be involved.
  5. Scope questions are coming into play, helping to further define Vector's purpose and scope.
  6. Previous RFCs are not easily discoverable.

Solution

I'd like to formalize our RFC process. I use "formalize" loosely. It is a step up from our current process but I do not intend it to be nearly as formal as real RFCs. The amount of time and effort involved in a RFC should scale with the change. You can see what I'm talking about in the new /rfcs folder:

  1. RFCs will now follow a consistent pattern, which should reduce the cognitive load when reviewing RFCs.
  2. RFCs are easily discoverable. New team members can obtain context on previous substantial decisions.
  3. It shows that the project is professionally maintained, at least relative to your average open source project.
  4. It can be improved and evolved over time, ensuring we address specific issues that have "bitten us" in previous changes.
  5. Anyone in the community can weigh in on RFCs since they are more easily discoverable.

I'd like to get consensus from everyone on this change before it is implemented.

Signed-off-by: binarylogic <[email protected]>
Signed-off-by: binarylogic <[email protected]>
Signed-off-by: binarylogic <[email protected]>
@MOZGIII
Copy link
Contributor

MOZGIII commented Mar 1, 2020

If we're going to add RFCs as markdown docs, how about we also add https://github.com/DavidAnson/markdownlint? Not necessarily in this PR, but if we're going to work with markdown files even more - I think it makes a lot of sense. It supports nice things, like editor integration and autoformatting!


1. Search Github for previous issues and RFCs on this topic.
2. Open an issue representing the change for light discussion.
3. In the isuee, obtain consensus that a RFC is necessary.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is isuee a typo?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it’s my damn Apple keyboard. I’ll fix it.

@MOZGIII
Copy link
Contributor

MOZGIII commented Mar 3, 2020

So, a follow up from the sync up.

What if we put this in a separate repo? This should do a better job in isolating the RFC editing process from the code editing process. What are the benefits of having rfcs dir in the vector repo? I think there are inly the minor ones, like the usual “you have to clone just a single repo“. However, to work on an RFC one would have to always work on a dedicated branch of vector, and having a separate workspace with it’s own repo might be actually easier to switch to.

@LucioFranco
Copy link
Contributor

I am 👍 on a separate repo for rfcs.

@ghost
Copy link

ghost commented Mar 3, 2020

A few arguments for keeping RFCs inside the main Vector's repo:

  • People who watch Vector's PRs using GitHub notifications feature would automatically become notified about proposed RFCs.
  • It would be easier to reference issues/PRs in discussions of the RFCs, they would be rendered just as Update installation documentation #1234 rather than as fix: Fix build on macOS Catalina by explicitly invoking the shell leveldb-sys#1.
  • Contributors to the Vector repository would automatically have a "Contributor" badge in the discussions of the RFCs near their name.
  • Eventually we might want to link to the text of RFCs from the docs. If RFCs are in the same repo, it would be possible to just render them as special pages of the documentation website.

@MOZGIII
Copy link
Contributor

MOZGIII commented Mar 3, 2020

Note that instead of [timberio/leveldb-sys#1](https://github.com/timberio/leveldb-sys/pull/1) toy can just use https://github.com/timberio/leveldb-sys/pull/1:

[timberio/leveldb-sys#1](https://github.com/timberio/leveldb-sys/pull/1): timberio/leveldb-sys#1
https://github.com/timberio/leveldb-sys/pull/1: vectordotdev/leveldb-sys#1

Copy link
Member

@lukesteensen lukesteensen left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like to see an Alternatives section in the template, but otherwise this looks good to me.

@MOZGIII
Copy link
Contributor

MOZGIII commented Mar 4, 2020

A few arguments for keeping RFCs inside the main Vector's repo:

  • People who watch Vector's PRs using GitHub notifications feature would automatically become notified about proposed RFCs.
  • It would be easier to reference issues/PRs in discussions of the RFCs, they would be rendered just as Update installation documentation #1234 rather than as timberio/leveldb-sys#1.
  • Contributors to the Vector repository would automatically have a "Contributor" badge in the discussions of the RFCs near their name.
  • Eventually we might want to link to the text of RFCs from the docs. If RFCs are in the same repo, it would be possible to just render them as special pages of the documentation website.

To me personally, I only see the last one as really beneficial. If we plan to link RFC on the website - we'll have an easier life if it's in the website repo - that currently being the vector repo. However, we might want to move it out as well (only leaving the docs in the vector repo, since they and the code have a shared lifecycle).

If we have two repos, people will be able to watch just one of them - for example, somebody might be interested only in the RFCs. So, in regards to repo watching, there are two sides to the coin.

Signed-off-by: binarylogic <[email protected]>
@binarylogic binarylogic merged commit af77563 into master Mar 5, 2020
@binarylogic binarylogic deleted the rfcs branch March 5, 2020 17:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants