Rfc

#repot (Private)

This is the place to propose and track major upcoming changes to Dendron and other related projects. It also is a great place to learn about the current and future state of the system and to discover projects for contribution.

Jump to: What is an RFC? | When to submit? | RFC States |

What is an RFC?

An RFC is a document that proposes and details a change or addition to Dendron and other related tooling. It is also a process for reviewing and discussing the proposal and tracking its implementation. "Request for Comments" means a request for discussion and oversight about the future of Dendron from contributors and users. It is an open forum for suggestions, questions, and feedback.

The process is intended to be as lightweight and reasonable as possible for the present circumstances. As usual, we are trying to let the process be driven by consensus and community norms, not impose more structure than necessary.

The RFC process itself is subject to changes as dictated by the core team and the community. Proposals can include proposed changes to the RFC process itself to better serve contributors.

When to submit an RFC?

You should consider using this process if you intend to make "substantial" changes to Dendron or related tools. Some examples that would benefit from an RFC are:

• Major new features where the desired exprience is ambiguous.
• Any change to existing APIs that could break existing code.
• The removal of existing features or public APIs.
• Changes to the documented contribution workflow.
• Features that cross multiple construct libraries.
• Additions or changes to framework capabilities.

The RFC process is a great opportunity to get more eyeballs on your proposal before it becomes a part of a released version of Dendron. Quite often, even proposals that seem "obvious" can be significantly improved once a wider group of interested people have a chance to weigh in.

The RFC process can also be helpful to encourage discussions about a proposed feature as it is being designed, and incorporate important constraints into the design while it's easier to change, before the design has been fully implemented.

If you submit a pull request to implement a new major feature without going through the RFC process, it may be closed with a polite request to submit an RFC first.

Some changes do not require an RFC:

• Bugfixes for known issues.
• Additions only likely to be noticed by other developers of Dendron, invisible to end product users.

If you're not sure whether your change requires an RFC, feel free to create an issue and ask.

RFC Process

In short, to get a major feature added to Dendron, one usually writes an RFC as a markdown file and gets it approved and mergd into the Dendron-site. At that point the RFC is 'in review' and may be implemented.

1. Create a tracking issue for the proposed feature if one doesn't already exist. If a tracking issue already exists, make sure to update it and assign it to let others know you're working on a proposal. tracking issue number and <my-feature> is the rfc title.
2. Fill in an RFC under the rfc.* hierarchy on dendron-site. Use the Rfc template (Private) when creating a RFC. We recommend that you add this repository to your workspace by following the instructions here (Private).
3. Submit a pull request with the title RFC: ### <title> where ### is the tracking issue number and title is the name of the proposal. As a pull request the RFC will receive design feedback from the core team and the larger community, and the author should be prepared to make revisions in response.
4. Update the tracking issue with a link to the RFC PR.
5. Promote your RFC amongst stakeholders via Discord. Build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those that don't receive any comments.
6. Eventually, the team will decide whether the RFC is a candidate for inclusion in a future release of Dendron.
7. RFCs that are candidates for inclusion will enter a "final comment period" lasting 3 calendar days. The beginning of this period will be signaled by a team member adding a comment and label on the RFCs pull request.
8. An RFC can be modified based upon feedback from the team and community. Significant modifications may trigger a new final comment period. An RFC can also be modified after it has been merged and approved, in which case a new PR will be submitted with the modification, like any other code.
9. An RFC may be rejected by the team after public discussion has settled and comments have been made summarizing the rationale for rejection. A member of the team will then close the PR and issue.
10. An RFC may be accepted at the close of its final comment period. A team member will merge the RFCs associated pull request, at which point the RFC will become 'approved'.
11. At some point, someone will pick up the RFC for implementation. For major features this usually requires devising a detailed implementation plan. To that end, submit an additional PR on the RFC doc that either fills in the "Implementation Plan" section or references a separate document or GitHub Project Board which includes the plan.
12. Once this PR is approved, the RFC will move to the 'implementing' state. Usually we track implementation using GitHub projects.
13. Once implementation is complete, the RFC moves to 'done', and it's issue is closed.

If the submitter is someone from our community (i.e., not core team member), a core team member will be assigned to 'shepherd' each proposal. They will generally be the ones updating the RFCs state in the tracking issue as it moves through the process. They can decide when a final comment period is triggered.

RFC States

1. 💡 proposed - A tracking issue has been created with a basic outline of the proposal.
2. ✍️ review - An RFC document has been written with a detailed design and a PR is under review. At this point the PR will be assigned a shepherd from the core team.
3. 👍 approved - The RFC PR is approved and merged to master, and the RFC is now ready to be implemented.
4. 🗺️ planning - A PR is created with the Implementation Plan section of the RFC.
5. 👷 implementing - Implemetation plan is approved and merged and the RFC is actively being implemented.
6. 1️⃣ phase one done - Implementation for phase 1/2/3 is complete. These phases will be determined in the RFC and a single RFC can have at maximum 3 phases.
7. ✅ done - Implementation is complete and merged across appropriate repositories.
8. 👎 rejected - During the review period, the RFC may be rejected and then it will be marked as such.
9. 👩‍🌾 community issue - This RFC is accepted but is not currently part of our roadmap. We will leave this as a community project for gardeners that are interested in taking this on.

Dendron's RFC process looks up to AWS CDK RFC process, Yarn RFC process, Rust RFC process, React RFC process, and Ember RFC process

• Dendron Developer Docs