This repo holds RFCs for the Aries project. They describe important topics (not minor details) that we want to standardize across the Aries ecosystem.
See this doc for a current listing of all RFCs and their statuses.
There are 2 types of RFCs:
- RFCs that describe individual features (the /features folder)
- RFCs that explain concepts underpinning many features (the /concepts folder)
RFCs are for developers building on Aries. They don't provide guidance on how Aries implements features internally; individual Aries repos have design docs for that.
RFCs go through a standard lifecycle:
-
To propose an RFC, raise a PR against this repo. Proposed RFCs are considered a Work in Progress. Status => PROPOSED
-
To get an RFC accepted or merged, build consensus for your RFC on chat and in community meetings. RFCs are merged as soon as the community thinks they reasonably embody an idea worth standardizing. An accepted RFC is incubating on a standards track. Status => ACCEPTED
-
To get an RFC adopted, socialize and implement. Once a RFC has momentum, it is formally given the "adopted" status. This happens when implementations accumulate, or when the mental model it advocates has begun to permeate our discourse. In other words, adoption is acknowledgment of a de facto standard. Status => ADOPTED
-
To refine an RFC, propose changes to it through additional PRs. Typically these changes are driven by experience that accumulates during or after adoption. Minor refinements that just improve clarity can happen inline with lightweight review. Status is still ADOPTED
Significant refinements require a superseding document; the original RFC is superseded with a forwarding hyperlink, not replaced. Status => SUPERSEDED
RFCs that are not on the brink of changing status are discussed through Github Issues. Any community member can open an issue; specify the RFC number in the issue title so the relationship is clear. For example, to open an issue on RFC 0025, an appropriate title for the issue might be:
RFC 0025: Need better diagram in Reference section
When the community feels that it's reasonable to suggest a formal status change for an RFC, best efforts are made to resolve all open issues against it. Then a PR is raised against the RFC's main README.md, where the status field in the header is updated. Discussion about the status change typically takes place in the comment stream for the PR, with issues being reserved for non-status-change topics.
Use a RFC to advocate substantial changes to the Aries ecosystem, where those changes need to be understood by developers who use Aries.
Before writing a RFC, consider exploring the idea on chat, on community calls (see the Hyperledger Community Calendar), or on aries@lists.hyperledger.org. Encouraging feedback from maintainers is a good sign that you're on the right track.
- Fork the RFC repo.
- Pick a folder name for your RFC. The name should consist of a zero-padded
4-digit number plus a descriptive name for the topic. Use lower-kebab-case
for the descriptive name. Get the RFC number by finding the number
of the most recent pull request
and incrementing by 1. For example, if the highest numbered PR is 125, your
RFC number would be 126. You should end up with a folder name like
0026-my-cool-feature. - Create the folder and copy
0000-template.mdtotext/<your folder name>/README.md. - Fill in the RFC. Put care into the details: RFCs that do not present convincing motivation, demonstrate an understanding of the impact of the design, or are disingenuous about the drawbacks or alternatives tend to be poorly received. You can add supporting artifacts, such as diagrams and sample data, in the RFC's folder.
- Submit a pull request.
Make sure that all of your commits satisfy the DCO requirements of the repo.
The RFC Maintainers will check to see if the process has been followed, and request any process changes before merging the PR.
When the PR is merged, your RFC is now in the PROPOSED state.
After your RFC has been proposed, the RFC will receive feedback from the larger community, and the author should be prepared to revise it. Updates may be made via pull request, and those changes will be merged as long as the process is followed.
When you believe that the RFC is mature enough (feedback is somewhat resolved, consensus is emerging, and implementation against it makes sense), submit a PR that changes the Status to ACCEPTED. The status change PR will remain open until the maintainers agree on the status change.
NOTE: contributors who used the Indy HIPE process prior to May 2019 should see the acceptance process substantially simplified under this approach. The bar for acceptance is not perfect consensus and all issues resolved; it's just general agreement that a doc is "close enough" that it makes sense to put it on a standards track where it can be improved as implementation teaches us what to tweak.
An accepted RFC is a standards-track document. It becomes an acknowledged standard when there is evidence that the community is deriving meaningful value from it. So:
- Implement the ideas, and find out who else is implementing.
- Socialize the ideas. Use them in other RFCs and documentation.
- Update the agent test suite to reflect the ideas.
When you believe an RFC is a de facto standard, raise a PR that changes the status to ADOPTED. If the community is friendly to the idea, the doc will enter a two-week "Final Comment Period" (FCP), after which there will be a vote on disposition.
This repository is licensed under an Apache 2 License.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the repo by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.
The structure and a lot of the initial language of this repository was borrowed from Indy HIPEs, which borrowed it from Rust RFC. Their good work has made the setup of this repository much quicker and better than it otherwise would have been. If you are not familiar with the Rust community, you should check them out.