Skip to content

Commit

Permalink
docs: support rfc process
Browse files Browse the repository at this point in the history
  • Loading branch information
joelfoliveira committed Oct 2, 2023
1 parent 0057d79 commit 774d065
Show file tree
Hide file tree
Showing 3 changed files with 70 additions and 0 deletions.
1 change: 1 addition & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Please describe the tests that you ran to verify your changes.
- [ ] I have performed a self-review of my own code
- [ ] I have added tests to cover my changes
- [ ] I have made corresponding changes to the documentation
- [ ] This change is related to an RFC document, and I've linked it in the Pull Request. RFCs aren't required to contribute. KafkaFlow uses them to document complex and/or impactful evolutions. You can now more about them at the [Contributing Guidelines](https://github.com/Farfetch/)kafkaflow/blob/master/CONTRIBUTING.md).

### Disclaimer

Expand Down
5 changes: 5 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,11 @@ Please note that this project is released with a [Contributor Code of Conduct][c

We recommend [opening an issue](https://github.com/Farfetch/kafkaflow/issues) before a substantial Pull Request if there isn’t [already an issue](https://github.com/Farfetch/kafkaflow/issues) for what you’d like to contribute. This helps facilitate a discussion before deciding on an implementation approach.

In case the change you want to propose can be considered impactful or complex, before creating a pull request, we encourage the use of [RFCs](https://github.com/Farfetch/kafkaflow/tree/master/rfcs) (Request for Comments) in our open-source project. RFCs serve as a valuable platform for fostering community discussion and gathering feedback on impactful or complex changes. They also play a crucial role in documenting such changes for transparency and reference.
When should you consider creating an RFC? If your proposed change falls under categories like architectural modifications, significant feature additions, major performance improvements, or any change likely to generate debate, it's an excellent candidate for an RFC.
To initiate the RFC process, use our RFC template located in `rfcs/0000-rfc-template.md`. Duplicate and rename the file according to the RFC number and purpose, then provide the necessary details about your change within the RFC file. Remember to store any RFC-related resources, such as images, in the `rfcs/resources` folder.
After the RFC has been approved and merged, you can then open a pull request with the implementation in conformity with what was discussed during the RFC.

For some changes, such as typo fixes, documentation enhancements, or broken links, it may be suitable to open a small Pull Request by itself.

### How to open a Pull Request
Expand Down
64 changes: 64 additions & 0 deletions rfcs/0000-rfc-template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
- Feature Name: (fill me in with a unique ident, `my_feature_name`)
- Start Date: (fill me in with today's date, YYYY-MM-DD)
- RFC PR(s): (add the reference to the PR where this RFC was proposed and discussed, can only be added after the PR has been created)
- Issue(s): (reference issue related with RFC proposal)
---

# RFC Name

## Summary

[summary]: #summary

This is a one paragraph explanation of the issue and the proposal.

## Motivation

[motivation]: #motivation

This section details why we are doing something, what use cases it supports, and what we expect the outcome to be.

## Guide Implementation

[guide-level-explanation]: #guide-level-explanation

This is a high-level overview of the process. In this section, explain the proposal like you were teaching it to a new community member. That means you're probably including:

* Introduction of new named concepts
* Explain things in terms of examples
* Explain the impact and how the feature and its goals can be approached at implementation.
* If applicable, provide sample errors / warnings / or migration guidance

## Reference Implementation

[reference-level-explanation]: #reference-level-explanation

This section provides space for deep technical details as required in the RFC. You need to hit on the following points in your reference implementation:

* It's interaction with other features
* It is reasonably clear how this would be implemented
* Corner cases are addressed through example
You can (and should) expand on the examples you used in the Guide Implementation and provide additional context.

## Drawbacks

[drawbacks]: #drawbacks

You should explain why we _wouldn't_ do this. There is a cost associated with these changes, and while there wouldn't be an RFC if the benefits didn't outweigh the drawbacks, your readers might not know all of the tradeoffs being made.

## Rationale / Alternatives

[rationale-and-alternatives]: #rationale-and-alternatives

You need to answer why this design is the right design. To do so, you need to understand all of the possible alternatives. You should list alternate designs and ideas and why they weren't considered for the solution. This ensures due diligence has been done on the proposal.

## Unresolved Questions

[unresolved-questions]: #unresolved-questions

You should gather any open questions and either list them in the document (folks often use markdown quoting) or add them to this section at the end of the document. If you want to mark unresolved options inline

**Open Question:** this is an open question

Is the common format used. The quote and bold combination (plus its indent) makes it easy to spot when reading through the document.

0 comments on commit 774d065

Please sign in to comment.