rfc.md (4062B)
1 # RFC process 2 3 Large and important changes to the Hare programming language are implemented by 4 a formal process of consensus with a "request for comments" (RFC). 5 6 ## When to prepare an RFC? 7 8 You may prepare an RFC for any change that you want to have a structured 9 discussion about, large or small. The author of a proposed change may opt-in to 10 the RFC process if they would find it useful for their work, or a maintainer or 11 reviewer may invoke the RFC process for a given change at their discretion. 12 13 As a rule of thumb, a change is more likely to require an RFC if any of the 14 following conditions are met: 15 16 - A change is controversial and requires discussion to secure consensus 17 - A standard library change breaks a widely-used API 18 - A language change requires most Hare users to rewrite their code 19 - A large number of subsystems are implicated 20 21 ## 0. Prior to submitting an RFC 22 23 Ideas can form anywhere, but once you want to turn an idea into action it is 24 important to discuss it in the official community spaces so that you can keep 25 those affected in the loop and prepare people to participate in the consensus 26 process. You can discuss ideas and early proposals, workshop RFC text, and so 27 on, in the Hare IRC channels and mailing lists. 28 29 Do some research to see which community members should participate in the 30 discussion, including at a minimum the maintainers of relevant subsystems and a 31 global maintainer. Seek out their feedback and guidance on your propsal. 32 33 ## 1. Submitting an RFC 34 35 RFCs are formally submitted to the [hare-rfc] mailing list. The subject line 36 should be "[RFC v1] Subject...", where v1 increments for each revision of the 37 proposal. Work-in-progress proposals may be submitted to this list with the 38 "[DRAFT RFC]" subject prefix. 39 40 The body of the RFC is free-form text, which should be formatted in accordance 41 with typical [mailing list etiquette][0], and should include at a minimum the 42 details of the proposed change, the rationale for the change, and the predicted 43 impact of the change to end-users. Illustrative code samples and other 44 supporting materials are encouraged to be included. See doc/rfc-template.txt for 45 a sample RFC to get started. 46 47 [hare-rfc]: https://lists.sr.ht/~sircmpwn/hare-rfc 48 [0]: https://man.sr.ht/lists.sr.ht/etiquette.md 49 50 You can start implementing the change proposed by the RFC for research or 51 illustrative purposes, but keep in mind that following the discussion of the RFC 52 much of this code might have to be rewritten. 53 54 ## 2. Discussion 55 56 The proposal is discussed following its submission, and will likely be refined. 57 Participants will narrow down the details, determine if the implications are 58 completely enumerated, and make plans for the implementation. This process will 59 generally result in the RFC draft being adjusted to incorporate feedback and 60 resubmitted with a new version number. 61 62 ## 3. Approval 63 64 A RFC does not require explicit approval to proceed to the implementation, 65 though patch authors would be wise to read the room to determine if the 66 potential code reviewers are satisfied with the status of the proposal, lest you 67 write code based on it which will ultimately be rejected for foreseeable 68 reasons. 69 70 ## 4. Implementation 71 72 Once the discussion participants are satisfied with the proposed RFC, the 73 proposal authors (and/or anyone they convinced to help out during the 74 discussion) should move forward with implementing the proposal and sending out 75 the relevant patches. 76 77 Once the implementation is complete, the authors should follow-up on the 78 original proposal thread on the hare-rfc mailing list with details about the 79 implementation (such as links to the relevant patches) to close the proposal and 80 record its implementation for posterity. 81 82 Proposal authors are also encouraged during the implementation phase to continue 83 commenting on the RFC thread to record new insights, document deviations from 84 the proposal that occured in practice, or to go back to the drawing board and 85 prepare a new revision with the lessons learned from the code. 86 87 ## FAQ 88 89 ### Who can submit an RFC? 90 91 Anyone.