I am of the belief along with several others that more comprehensive feature requirements early in the development process can:
- lead to better/more efficient discussions - help achieve a higher level of transparency across groups - help to break down the work so it can be "tasked" - lead to better estimates - help identify any risks associated with the new feature - mitigate the risk of "delivering the wrong thing" - produce better tests - help identify operational costs - help identify deployment impacts/cost - help develop deployment procedures - help identify workarounds - etc - etc Therefore, several of us at Comcast have come up with what we think is a relatively simple feature template (we call it a blueprint) designed to capture the initial requirements of a feature and facilitate discussion and generate feedback. It was designed to be lightweight yet comprehensive. We plan to use this blueprint template internally at Comcast for new TC features, however, we thought it might have value in the TC open source community as well. I've opened a PR that includes the blueprint template plus 2 examples of its use: https://github.com/apache/trafficcontrol/pull/3884 If this is something we want to do in open source, here is the idea. When proposing a new feature, a developer can optionally: 1. Create a new PR that includes a markdown file that utilizes the BLUEPRINT_TEMPLATE.md template. For example, submit a PR to TC to blueprints/my-feature.md 2. Send an email to the dev list with a short description of your feature plus a link to the blueprint PR 3. Wait for feedback to be applied to your blueprint PR. (because it's a PR, line-specific feedback can be given.) 4. Just like any PR, once all the concerns have been addressed, the blueprint is merged into the blueprints directory (if accepted) or closed (if rejected). 5. Start work on the feature 6. Submit a PR for the feature and reference the blueprint. Of course, this can be OPTIONAL. Contributors can still create features without a blueprint or maybe some contributors feel more comfortable demonstrating a feature with working code. However, some contributors may want to use a feature blueprint to "bounce ideas off the group" and gain some consensus before moving forward. IMO the way we discuss requirements/design now in email is very inefficient / painful plus it's hard to get a good snapshot of the final design without going back thru the entire email thread. You also may be asking yourself "why not just create an issue instead?". The reason is because "issues" can't be commented on at the line level and issues tend to get lost. The blueprints would build up in the blueprints directory for later reference if needed. If this is not something our open source community wants to embrace, that is fine too. We can keep this as an internal Comcast thing and I can simply close the PR. Thoughts?
