Use GitHub Discussions for RFCs

[SoumayaMauthoorMOJ]

• Superseded by: N/A
• Related: N/A

Summary

Use GitHub Discussions to document proposed design changes as lightweight RFCs, placing each one in the most relevant repository. Add the 'RFC' label to make them easy to search across multiple repositories.

Motivation

Data and analytics engineering teams are already using GitHub discussions to propose design changes e.g. dimensional and data marts. These are stored in multiple repositories. This RFC proposes a consistent, light-weight documentation approach for such design changes that makes it easy for people to find.

Detailed Design

1. Add Discussion template with the category "RFC", labels "RFC" "Draft" and vuejs RFC template
2. Once ready, set discussion label to "Discussion"
3. Once agreed, set discussion label to "Active" and lock conversation
4. Otherwise, close discussion as outdated
5. Use discussion title as RFC title (no need to add "RFC" prefix)
6. No need to generate RFC ID since you can use the GitHub-generated URL ID
7. To find relevant RFCs, search by label "RFC" e.g. test instead of searching by category because doesn't work when searching globally
8. Chase Github about adding discussions to projects so that in the future we can set status and flag all RFCs in a central location

Drawbacks

• GitHub discussion search is less advanced that GitHub code search
• GitHub discussions cannot be added to GitHub projects
• Harder to track changes to RFC within discussion summary

Alternatives

Store RFCs in Markdown and associate with PR

Based on reactjs RFC Process:

• Store RFCs in Markdown and associate with PR
• Make sure that RFC title and ID matches with PR title and ID
• Merge in RFC once Active
• Use PR status to reflect RFC status (but not superseded): Draft | Ready for review | Merged | Closed without merging
• Colleagues can provide feedback on PR through comments

Cons:

• More complicated than creating/updating GitHub discussion which can discourage people from writing RFCs
• Easy to end up with more than one PR per RFC which messes up workflow
• PR comments have less features than discussion comments
• RFC text cannot be searched until PR is merged

Pros:

• PRs can be added to a centralised GitHub project, unlike Discussions
• Easier to track changes to RFC using git
• RFC and comments about the RFC are more clearly separated and less likely to "bleed" into each other
• PR status provides intuitive mechanism for tracking RFC status

Store RFCs in Issues with label "RFC"

Similar to using GitHub discussions but using GitHub issues instead.

Cons:

• Counterintuitive to store RFCs as an issue
• Issue comments have less features than discussion comments

Pros:

• Issues can be added to a centralised GitHub project and assigned a status
• GitHub has better support for searching Issues than discussions

Unresolved questions

1. How to notify people when a GitHub discussion has been created that they might be interested in