I'm a big fan of documentation and like the idea. The template is very verbose- i wouldn't want to fill that out if I was proposing a new feature. Can it be simplified at all? In the 2 examples given, most of the sections are left blank. What about a generic prompt such as: "Describe changes to each Traffic Control component. Any changes to external interfaces (DBs, APIs, Schemas) or existing behavior should be included. Also consider how this may impact security and performance of the overall system".
Once the feature is built and merged, how does the blueprint get folded back into the docs? Should we expect every blueprint to result in updated read-the-docs? On Wed, Aug 21, 2019 at 11:27 PM Chris Lemmons <[email protected]> wrote: > 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? >
