This is potentially a cool idea. I like that it doesn't require a wiki account and it gets feedback directly in the form of a PR.
On Tue, Aug 20, 2019 at 3:22 PM Jeremy Mitchell <[email protected]> wrote: > > 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?
