Open Stack

On 21/11/13 02:28, Steve Gordon wrote:
> Hi all,
>
> I've been musing for a while about the way we pick up changes that impact documentation, the timing of this is somewhat poor given our current bug backlog (as I suspect any improvement/solution would involve yet more work ;)) but thought I'd best open the discussion anyway to see what others thoughts are on this topic. Currently we get notification of a change that (potentially) impacts documentation when the change is merged and has the DocImpact flag set in the commit message.
>
> Reading over Russell's recent proposal on openstack-dev for improving the Nova blueprint process (forwarded in its entirety below) - an approach I'd love to see other PTLs adopt -  I noticed this statement in the context of what blueprint reviewers should be looking for before approving a blueprint:
>
>>   - includes information that describes the user impact (or lack of).
>>     Between the blueprint and text that comes with the DocImpact flag [3]
>>     in commits, the docs team should have *everything* they need to
>>     thoroughly document the feature.
>
> In isolation this is arguably "as it should be". What I think still makes me uneasy about the way we receive change notification in documentation is that:
>
> * Regardless of whether the above is achieved or not by the time we get notified the horse has bolted - the blueprint has been approved and the code has merged - so even if we *don't* in the end have enough information in the blueprint/commit there doesn't seem to be a feedback loop to the reviewers for next time. Instead we'd typically try and track down the author of the change directly and get the information from them, this works but adds an additional round of interactions and potential delays that could be avoided if we had better information up front.
>
> * While theoretically we should get a steady flow of inbound work over each code milestone there is (predictably) a big jump with the feature freeze and associated final milestone. I'm not sure there is any way to better prepare ourselves for this but I'm including this as a concern rather than something I have a solution for ;). In theory I think more concise blueprints and commit messages would at least help ensure that when this jump occurs the changes are more easily actionable for writers who aren't necessarily deeply aware of the ins and outs of every individual project.
>
> Personally I am going to attempt to pay closer attention to blueprints coming through and provide commentary (although it's already really too late for icehouse-1 - time flies when you are having fun!), but I was wondering if there is interest in being more proactive/organized approach to this from the wider documentation team (I'm thinking something like trying to have one person from docs review blueprints from each core/integrated project or something like that)?
>
> Thanks,
>
> Steve, your friendly rambling lunatic ;).

Just data points:

* We used to have DocImpact bug creation / email on first patchset 
submission - even while WIP or Draft.
* We changed this to only create bugs after patches were merged
* This was because,
1) The emails were more or less useless
2) There was requirement for constant followup on reviews with lodged 
bugs to check the status, which ended up not getting done regularly 
anyway (I just waited for weeks and did a bunch once I knew the 
likelihood of them being merged was high) because it was simply too much 
work for one person doing it in their spare time


Regards,

Tom


> ----- Forwarded Message -----
>> From: "Russell Bryant" <rbryant at redhat.com>
>> To: "OpenStack Development Mailing List" <openstack-dev at lists.openstack.org>
>> Sent: Wednesday, October 23, 2013 11:33:14 AM
>> Subject: [openstack-dev] [Nova] Blueprint review process
>>
>> Greetings,
>>
>> At the last Nova meeting we started talking about some updates to the
>> Nova blueprint process for the Icehouse cycle.  I had hoped we could
>> talk about and finalize this in a Nova design summit session on "Nova
>> Project Structure and Process" [1], but I think we need to push forward
>> on finalizing this as soon as possible so that it doesn't block current
>> work being done.
>>
>> Here is a first cut at the process.  Let me know what you think is
>> missing or should change.  I'll get the result of this thread posted on
>> the wiki.
>>
>> 1) Proposing a Blueprint
>>
>> Proposing a blueprint for Nova is not much different than other
>> projects.  You should follow the instructions here:
>>
>>      https://wiki.openstack.org/wiki/Blueprints
>>
>> The particular important step that seems to be missed by most is:
>>
>> "Once it is ready for PTL review, you should set:
>>
>> Milestone: Which part of the release cycle you think your work will be
>> proposed for merging."
>>
>> That is really important.  Due to the volume of Nova blueprints, it
>> probably will not be seen until you do this.
>>
>> 2) Blueprint Review Team
>>
>> Ensuring blueprints get reviewed is one of the responsibilities of the
>> PTL.  However, due to the volume of Nova blueprints, it's not practical
>> for me to do it alone.  A team of people (nova-drivers) [2], a subset of
>> nova-core, will be doing blueprint reviews.
>>
>> By having more people reviewing blueprints, we can do a more thorough
>> job and have a higher quality result.
>>
>> Note that even though there is a nova-drivers team, *everyone* is
>> encouraged to participate in the review process by providing feedback on
>> the mailing list.
>>
>> 3) Blueprint Review Criteria
>>
>> Here are some things that the team reviewing blueprints should look for:
>>
>> The blueprint ...
>>
>>   - is assigned to the person signing up to do the work
>>
>>   - has been targeted to the milestone when the code is
>>     planned to be completed
>>
>>   - is an appropriate feature for Nova.  This means it fits with the
>>     vision for Nova and OpenStack overall.  This is obviously very
>>     subjective, but the result should represent consensus.
>>
>>   - includes enough detail to be able to complete an initial design
>>     review before approving the blueprint. In many cases, the design
>>     review may result in a discussion on the mailing list to work
>>     through details. A link to this discussion should be left in the
>>     whiteboard of the blueprint for reference.  This initial design
>>     review should be completed before the blueprint is approved.
>>
>>   - includes information that describes the user impact (or lack of).
>>     Between the blueprint and text that comes with the DocImpact flag [3]
>>     in commits, the docs team should have *everything* they need to
>>     thoroughly document the feature.
>>
>> Once the review has been complete, the blueprint should be marked as
>> approved and the priority should be set.  A set priority is how we know
>> from the blueprint list which ones have already been reviewed.
>>
>> 4) Blueprint Prioritization
>>
>> I would like to do a better job of using priorities in Icehouse.  The
>> priority field services a couple of purposes:
>>
>>    - helps reviewers prioritize their time
>>
>>    - helps set expectations for the submitter for how reviewing this
>>      work stacks up against other things
>>
>> In the last meeting we discussed an idea that I think is worth trying at
>> least for icehouse-1 to see if we like it or not.  The idea is that
>> *every* blueprint starts out at a Low priority, which means "best
>> effort, but no promises".  For a blueprint to get prioritized higher, it
>> should have 2 nova-core members signed up to review the resulting code.
>>
>> If we do this, I suspect we may end up with more blueprints at Low, but
>> I also think we'll end up with a more realistic list of blueprints.  The
>> reality is if a feature doesn't have reviewers agreeing to do the
>> review, it really is in a "best effort, but no promises" situation.
>>
>> 5) Blueprint Fall Cleaning
>>
>> Finally, it's about time we do some cleaning of the blueprint backlog.
>> There are a bunch not currently being worked on.  I propose that we
>> close out all blueprints not targeted at a release milestone by November
>> 22 (2 weeks after the end of the design summit), with the exception of
>> anything just recently filed and still being drafted.
>>
>>
>> [1] http://summit.openstack.org/cfp/details/341
>> [2] https://launchpad.net/~nova-drivers/+members#active
>> [3]
>> http://justwriteclick.com/2013/09/17/openstack-docimpact-flag-walk-through/
>>
>> --
>> Russell Bryant
>>
>> _______________________________________________
>> OpenStack-dev mailing list
>> OpenStack-dev at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>