search

artsy / README

:wave: - The documentation for being an Artsy Engineer
Creative Commons Attribution 4.0 International
1.1k stars 120 forks source link

rfc: use PRs instead of issues for RFCs #467

Closed admbtlr closed 2 years ago

admbtlr commented 2 years ago

Proposing a new approach for RFCs.

kathytafel commented 2 years ago

OMG what a lightweight process upgrade. I love it.

pvinis commented 2 years ago

One thing i would like to have defined/cleared up, is if we should use the PR desc or just keep everything on the PR files. I think PR files makes more sense, but I would like it if all of us follow one way.

Another thing, is about how we handle changes/reviews. In my mind, it makes sense to only leave comments on the PR and comments on the PR files/lines. It seems strange to use approvals/request changes. Seems like the author should be the one responsible to either merge or close, with the final comment of the next steps. Is that what you have in mind? How are you thinking of all that?

admbtlr commented 2 years ago

One thing i would like to have defined/cleared up, is if we should use the PR desc or just keep everything on the PR files. I think PR files makes more sense, but I would like it if all of us follow one way.

Another thing, is about how we handle changes/reviews. In my mind, it makes sense to only leave comments on the PR and comments on the PR files/lines. It seems strange to use approvals/request changes. Seems like the author should be the one responsible to either merge or close, with the final comment of the next steps. Is that what you have in mind? How are you thinking of all that?

The outcome of an RFC should be the new markdown document that the PR is proposing to add. This document represents the content of the RFC and, once merged, is itself a permanent record of the org's decision to accept and act on the RFC.

So yes, the discussion should take place within the context of the document, and the PR description can be left empty. Or just include a brief summary of the document, as I did here.

And yes, it's probably easier to use 👍 / 👎 reactions on the PR description, rather than approving / requesting changes. And yes, it should be the author who merges or closes the PR, based on the votes and discussion.

patrinoua commented 2 years ago

love this 🔥

damassi commented 2 years ago

It just makes an enormous amount of sense 👍 Nice idea @admbtlr.

jacobherrington commented 2 years ago

The outcome of an RFC should be the new markdown document that the PR is proposing to add. This document represents the content of the RFC and, once merged, is itself a permanent record of the org's decision to accept and act on the RFC.

100% agree with this line of thinking.

mdole commented 2 years ago

yeah, I especially like the idea of this resulting in living documents in this repo so people can easily see and make updates to RFCs if the need arises (@admbtlr seems like we should update the Markedown document this RFC introduces to include that part, right? 😉).

Let's do it!

joeyAghion commented 2 years ago

I'm very in favor of RFCs as PRs (and we've had a few). My preference is for the outcome to not just be a new doc in the RFCs/ directory, but corresponding updates to our playbooks, tech radar, etc. That's where the meat of significant process changes can be debated, and where a developer will look for succinct documentation rather than the whole of our RFC history. (Of course they can all be linked together, too.)

gkartalis commented 2 years ago

Love this idea, it makes so much sense! The best feature of this approach is the ability to let people provide in-context suggestions or changes! Thanks for bringing this up!

admbtlr commented 2 years ago

(@admbtlr seems like we should update the Markedown document this RFC introduces to include that part, right? 😉).

I added a little more detail in a new commit - does that cover it @mdole ?

mdole commented 2 years ago

LGTM! Thanks @admbtlr

pvinis commented 2 years ago

should we have a _template.md file in that RFCs folder, for easy copy/pasting and editing?