How to create Request for Comments

3 months ago

David Grudl
Nette Core | 7057

Here are some suggestions on how to create an RFC. I hope they help set expectations about the RFC process and feature acceptance in the Nette Framework.

  • Before starting an RFC, review existing RFCs and search the forum and GitHub issues for similar ideas. Use this information to explain what your RFC will bring to the framework.
  • If you're new to Nette core development, post on the forum to judge interest before you start your RFC. If you get no reaction (this is likely) or positive reaction then create the RFC. Core Nette developers with karma will know when they can skip this step.
  • There are many really good ideas for improving Nette, however some of them are really tedious or technically risky or hard. If you are about send on the forum post saying “someone should do …”, then don't hit “Send”. Work out how you could do it, and then send a patch.
  • If the overall goals of Nette are not clear to you, you may not be alone. However, as an RFC writer you need to learn the general trajectory of the framework and where web development is heading. You then need to enthuse everyone with your feature and show what it brings to the framework.
  • Your RFC will be used to create the documentation, so make its sections re-usable. Explain concepts and details. Keep the RFC technical and have plenty of examples.
  • An implementation is not mandatory while proposing an RFC but it can help persuade people and help fine-tune the design. Note that if you are unable to implement the RFC, and no one else volunteers during the discussion period, then your RFC is unlikely ever to be implemented.
  • Don't start an implementation too early. Get support for the feature concept from the Core users before spending time on coding – unless you want a learning experience.
  • It's easy to get sidetracked by forum trolling or well intentioned but over-eager discussion. Take advice on board but make sure your feature doesn't end up being designed by a committee. Don't blame the “Nette core community” for derailing discussions when the issues of non- code-contributors are at fault.
  • For every user who wants a backwardly incompatible change to Nette, there is a user who will scream that this will be disastrous to them. As the RFC writer you need to walk the line between these groups.
  • With long, fragmented discussions, not everyone will read every post. Update the RFC at regular intervals, and let people know what has changed.
  • Some areas of Nette are complex or niche. Sometimes feature suggestions will be greeted by an apparent lack of interest. Don't be discouraged. This just means you need to take a stronger leadership role, and also prove your credentials by first working on the existing code base.
  • Don't leave any ambiguity in the RFC. As well as stating what will be changed, also state what won't be changed. Ambiguity will hurt the chances of a successful outcome because voters will be unsure that the feature has been fully thought through. Make sure there are no “Open Issues” in the RFC when voting. Make a decision about the choices before opening the vote, or mark the issues clearly as “Future topics for exploration”.
  • Positive received ideas outcomes for RFCs that are just “concepts” can be interpreted as support for “good ideas” rather than being a definitive guarantee that a feature will appear in a future version of Nette. As a feature is later investigated and further discussed, the early vote may become irrelevant. Similarly, where there is no chance of an implementation being written, a positive poll outcome is just an indicator of desire.
  • If your RFC is rejected, it is not the end of the world. Sometimes ideas are submitted “before their time”, and it takes an acclimatization period for other developers to see their value. As the core Nette developer base goes through natural turn-over, revisiting an idea after a (long) period may result in different appreciation. See the previous points about becoming a core contributor – having karma goes a long way towards getting an RFC accepted, not only because experienced contributors know which RFCs are worth suggesting, and know how to make proposals understandable. When your RFC is rejected, continue working with the Nette core development community and revisit the RFC later.

In summary, the Nette development process is an organic process and subject to flexibility. It is based heavily around users contributing features that they require. This therefore requires high investment from users who want change. Very rarely do Nette core developers have bandwidth to take on external ideas, no matter how good they are. Feature acceptance has to be pragmatic. The core Nette contributors would love to see more people get commit karma and contribute to Nette.