diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 7bcea43fc..e2c6f0984 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7397e5cf3..5b21fba99 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/rfcs/0000-rfc-template.md b/rfcs/0000-rfc-template.md new file mode 100644 index 000000000..ba2d867b1 --- /dev/null +++ b/rfcs/0000-rfc-template.md @@ -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. \ No newline at end of file