1. Process

In order to add or make changes to the EcoStd standards one must get an RFC approved (i.e. proposed, discussed, voted on, and merged). Before following the steps below, make sure to read this entire process. As there are considerations to keep in mind that will improve the chances of your proposal being effective. The steps to submit an RFC are:

  1. Fork the RFCs repository.

  2. Copy the src/00/00-template-adoc (or src/00/00-template-md for Markdown [1]) directory to src/00/00-sliced-bread (change sliced-bread to something short, but descriptive).

  3. Write your RFC in the proposal.adoc (or proposal.md for Markdown [1]) file. If you need additional files you should place them only in the directory. It’s important, i.e. required, to properly fill in the authors and email metadata fields at the top with your information. As they are used for proper license attribution. Consult the Asciidoctor documentation, or on how to do that.

  4. Submit a pull request. In addition to the RFC itself you should provide a brief description in the pull request itself. Copy-pasting the RFC abstract into the PR description is minimally sufficient.

  5. Use the pull request number you now have to rename the src/00/00-my-proposal directory to match the PR number and fill the rfcpr field in proposal.adoc (or proposal.md for Markdown [1]) to match.

  6. At this time the RFC will be considered active and will be labeled accordingly. The RFC will receive initial feedback for which you will need to respond, preferably both in the PR comments and reflected in the RFC text itself.

  7. After some time, and sufficient discussion and interest, and if this is a proposal for a standard change (or addition) you will need to write wording for the standard and create a PR in the standard repository. You may also be directly asked to produce a wording PR if needed. When you have such a PR edit the RFC stdpr field. The RFC will be labeled either as needing wording and/or having wording as appropriate. The wording PR will be discussed in that PR and/or the RFC. The discussion may incur doing changes to the RFC.

  8. After sufficient time and discussion the combined RFC and wording PR will be considered ready for a decision on further progress. A member of the "adoption review group" will propose taking a vote for adoption.

  9. An adoption vote starts after three members of the review group agree. The vote will last at most 28 calendar days, and at least 7 calendar days. The length of the voting period will be part of the voting proposal. But the length is subject to community feedback before and during the voting. The RFC PR will be labeled accordingly to reflect the voting.

  10. When the adoption vote completes the RFC is either approved or rejected. The RFC will be labeled accordingly and may be closed.

  11. A rejected RFC PR may be closed depending on the reasons for rejection. The RFC may stay active, but go back to being discussed, if there are changes possible and reconsidered for approval.

  12. An approved RFC PR is closed, and labeled as adopted. The actions proscribed in the RFC are then taken up by others to complete. For RFCs that affect the standard will continue in the related PR by the "standard editors group".

Tip
 The preferred document format for RFCs is Asciidoctor. But the GitHub Flavored Markdown format is supported as an alternative. The extent of support is subject to what is supported by the conversion to Asciidoctor process as part of build the HTML for the RFCs website.

2. Guidelines

These are a loose collection of rules to follow, things to keep in mind, and background information that is useful when creating RFCs. They are grouped by the aspect of RFCs that they apply to:

Mechanics

Guidelines for the task of the RFC and PR itself.

Design

Guidelines for that help with the design content of an RFC.

These are guidelines, and not rules. They are expected to be true most times. But we allow for flexibility in the process. The goal is to reduce friction as much as possible without sacrificing comprehensive evaluation of RFCs.

2.1. Mechanics

Do not squash, or otherwise coalesce, changes for RFC PRs

After creating an RFC PR additional updates should be done as additional, plain, commits. Having the additional commits helps in tracking how feedback is addressed. When an RFC is approved it will be squash merged. Hence attempts to pre-squash would be wasted.

Mirror external feedback in the PR

Any feedback you get outside of PR comments should be summarized, by you, as comments in the PR. And if there are changes, i.e. additional commits, to the RFC that are related they should be mentioned in the PR comments.

Do not change approved PRs

After a PR is approved, and labeled as such, do not alter it. It will be merged in due time. If there are followup changes they should come as different RFCs.

2.2. Design

Prefer solutions that cast a wide net

The key goal of EcoStd is to facilitate wide adoption and interoperation. Hence single solutions that solve a wide scope are preferred. Which means that you can expect questions like: “Does this solve X, Y, and Z also?”, “Have you considered use case U?”, and more.

Including existing practice is essential for an RFC

Engineering is an iterative practice as such it makes progress from existing solutions towards better ones. Solutions without a problem are just dreams that are not likely widely shared. For those reasons, and more, it’s imperative that an RFC is based on existing practice, i.e. demonstrate that there’s a problem and solution that this is trying to improve.

Seek consensus with proposals and when responding to feedback

Because of the goal of this collective work is to achieve as widespread adoption as possible it’s important to consider the varied viewpoints when composing solutions to problems. You should seek consensus as much as possible at all times. There are many ways to achieve consensus, and it would be impossible to enumerate them. But some general ones are:

  • Provide rationale (pros and cons) for decisions and feedback.

  • Seek to increase factual data in your proposal.

  • Include real world examples and use cases.

  • Provide before and after comparisons if you are proposing behavior changes.

3. License

This repository, and all contributions to it, are licensed under CC BY 4.0.

4. Adopted RFCs

RFC Title Authors

0000-template-adoc

Proposal Template

René Ferdinand Rivera Morell

0000-template-md

Proposal Template

René Ferdinand Rivera Morell

0001-rfc-process

RFC Process

René Ferdinand Rivera Morell

5. Contributors

5.1. RFC Authors

  • René Ferdinand Rivera Morell

1. GitHub Flavored Markdown (https://github.github.com/gfm/)