+1 The number of sections and prompts is primarily just to cover all the bases. Depending on the scope of your changes, you will probably end up leaving a number of the per-component sections blank (because they simply won't be impacted at all). The prompts are mainly just there to prime the writer's brain and help the thought process -- the prompts aren't meant to all be answered for every single section. In fact, I would encourage the addition of prompts to all the various sections as everyone begins to think of new questions/prompts that would be important to add. If there are any prompts that don't really make sense or that we think would be more useful elsewhere, we should move them out. However, I think keeping all the various _sections_ is important because an explicit "n/a" is more clear than just deleting a section if it doesn't apply to your blueprint. It allows the writer to be explicit about sections that don't apply.
RE: the docs questions, I think blueprints are meant to be more for a developer-type audience whereas "the docs" are meant to be more for an end user audience. Blueprints will provide a good starting point for the user-facing documentation, but I don't think blueprints should be the _only_ documentation or even necessarily looped into "the docs" build process. My hope would be that they don't get any more complex than simple markdown with minimal overhead. - Rawlin On Thu, Aug 22, 2019 at 10:45 AM Jeremy Mitchell <[email protected]> wrote: > > Eric, > > I'm guessing most (all?) features _should_ probably be documented in > read-the-docs so i'd hope that the PR to implement that feature included > the documentation additions. I think it's up to the PR reviewers to ensure > that. > > As far as what happens to the blueprint, it just sits there in the > blueprints directory but it is referenced in the implementing PR so there > is an audit trail from the code to the PR to the blueprint that initiated > it all. Rob Butts mentioned maybe adding a status to the blueprint (i.e. in > progress or implemented). > > And yes, I like simplifying the template but i hate removing valid sections > that could serve as a reminder to blueprint reviewers. i.e. "hey, you put > N/A in `operations impact` but there most definitely is an operation > impact, specifically X" > > Jeremy > > On Thu, Aug 22, 2019 at 9:06 AM Eric Friedrich <[email protected]> > wrote: > > > 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? > > > > >
