High Level Summary
In summary, the OpenMAMA project subscribes to the following RFC process for major pieces of work:
Pre-requisites for raising an RFC
There are several recommended pre-requisites which should be considered before creating an RFC.
Talk to the community
Before going to the efforts associated with raising an RFC, it’s a good idea to solicit feedback from the community. The best way to do this is to send an email to the OpenMAMA Developer mailing list. You could find that a RFC isn’t even required and that a simple pull request containing your suggested changes would be sufficient.
Once an RFC becomes code, it becomes the project as a whole’s responsibility to maintain all related changes, so buy-in from the community to support these major changes should be established upfront.
Think it through
It’s easy to get into the realm of documenting things before thinking it through, then realising
that you need to backpedal and retro-fit changes because there were elements that you hadn’t
considered upfront. Before proceeding, have a skim through the
Raising and Writing an RFC
Before writing an RFC, it’s best to get up and running with a local jekyll server to allow you to preview all changes before submitting to github.
Fork the documentation repository by clicking the Fork button above the openmama.github.io repository
Clone a copy of your fork to your local machine:
git clone https://github.com/your-github-username/openmama.github.io.git
Set up jekyll for local previews (optional but recommended) - see our contribution documentation
Create your RFC page (copy and paste
Fill in the RFC Template
Do git add / commit / push etc to create a pull request for the project maintainer to approve
Once the submission is approved, notify the mailing list of the new RFC and invite participation from the community
Process for an in-flight RFC
Once an RFC has been raised, it is in the review process. The project maintainer will then respond with a deadline for the RFC after which point if no further changes are required, the matter will be considered closed. Under normal circumstances, this will last for 2 weeks, but if significant changes are required, this may be extended at the discretion of the project maintainer.
Once the deadline has expired and no further changes are required, the RFC is considered approved / closed and the contributor is free to begin work. The Closed RFC entry will then be updated with details on the resulting pull request / commit when it’s submitted.
How to provide RFC Feedback
How you would need to provide feedback depends on the nature of your contribution:
This is easily the preferred way to provide feedback for an RFC document. If you have a criticism about an element in a document, then you are encouraged to not just point out the error, but to submit suggestions to correct this. You can do so by clicking on the Edit link on an RFC and making changes through github. This can then be submitted through the GUI back to the page in the form of a pull request which can then be accepted if the suggested change is correct.
If your feedback is really around clarification or questioning of an item in the document, your best way to provide feedback is via the original mailing list thread created by the proposer. This is linked to in the final RFC documentation and is a good way to ensure that all related feedback is provided in full visibility of all interested parties.