Excerpts from Alexandra Settle's message of 2017-03-02 16:25:46 +0000:
> On 3/2/17, 4:08 PM, "Doug Hellmann" <d...@doughellmann.com> wrote:
>     Excerpts from Alexandra Settle's message of 2017-03-02 14:29:07 +0000:
>     > 
>     > 
>     > From: Anne Gentle <annegen...@justwriteclick.com>
>     > Date: Thursday, March 2, 2017 at 2:16 PM
>     > To: Alexandra Settle <a.set...@outlook.com>
>     > Cc: "OpenStack Development Mailing List (not for usage questions)" 
> <openstack-dev@lists.openstack.org>, "openstack-d...@lists.openstack.org" 
> <openstack-d...@lists.openstack.org>
>     > Subject: Re: [OpenStack-docs] [docs][release][ptl] Adding docs to the 
> release schedule
>     > 
>     > 
>     > 
>     > On Wed, Mar 1, 2017 at 11:52 AM, Alexandra Settle 
> <a.set...@outlook.com<mailto:a.set...@outlook.com>> wrote:
>     > Hi everyone,
>     > 
>     > I would like to propose that we introduce a “Review documentation” 
> period on the release schedule.
>     > 
>     > We would formulate it as a deadline, so that it fits in the schedule 
> and making it coincide with the RC1 deadline.
>     > 
>     > For projects that are not following the milestones, we would translate 
> this new inclusion literally, so if you would like your project to be 
> documented at docs.o.o, then doc must be introduced and reviewed one month 
> before the branch is cut.
>     > 
>     > I like this idea, and it can align certain docs with string freeze 
> logically.
>     > 
>     > I think the docs that are governed with this set of rules should be 
> scoped only to those that are synched with a release, namely the 
> Configuration Reference, Networking Guide, and Install Guides. [1]
>     > 
>     > For reference, those are the guides that would best align with "common 
> cycle with development milestones." [2]
>     > 
>     > Scope this proposal to the released guides, clarify which repo those 
> will be in, who can review and merge, and precisely when the cutoff is, and 
> you're onto something here. Plus, I can hear the translation teams cheering. 
> :)
>     > 
>     > 
>     > I completely agree with everything here :) my only question is, what do 
> you mean by “clarify which repo those will be in”? I had no intention of 
> moving documentation with this suggestion Install guides either in 
> openstack-manuals or their own $project repos :)
>     > 
>     > Next question – since there doesn’t appear to be a huge ‘no don’t do 
> the thing’ coming from the dev list at this point, how and where do we 
> include this new release information? Here? 
> https://docs.openstack.org/project-team-guide/release-management.html#release-1
>     > 
>     > Anne
>     > 
>     > 
>     > 1. 
> https://docs.openstack.org/contributor-guide/blueprints-and-specs.html#release-specific-documentation
>     > 
>     > 2. 
> https://docs.openstack.org/project-team-guide/release-management.html#common-cycle-with-development-milestones
>     > 
>     > 
>     > In the last week since we released Ocata, it has become increasingly 
> apparent that the documentation was not updated from the development side. We 
> were not aware of a lot of new enhancements, features, or major bug fixes for 
> certain projects. This means we have released with incorrect/out-of-date 
> documentation. This is not only an unfortunately bad reflection on our team, 
> but on the project teams themselves.
>     > 
>     > The new inclusion to the schedule may seem unnecessary, but a lot of 
> people rely on this and the PTL drives milestones from this schedule.
>     > 
>     > From our side, I endeavor to ensure our release managers are working 
> harder to ping and remind doc liaisons and PTLs to ensure the documentation 
> is appropriately updated and working to ensure this does not happen in the 
> future.
>     > 
>     > Thanks,
>     > 
>     > Alex
>     > 
>     As Thierry pointed out, we do need to consider the fact that more
>     projects are using the cycle-with-intermediary process, so although
>     we might tie dates to milestones we need to be careful that projects
>     not tagging milestones are still covered in any processes.
>     Based on a similar discussion we had with the i18n team at the PTG,
>     I think a good first step here is to document the agreement by
>     writing a governance tag with a name like doc:managed. The tag
>     description is the place to write down the answers to the questions
>     from this thread.
>     For example, it would list the manuals that are in scope, what
>     portion of the work the docs team will take on (initial writing?
>     reviews?), and what portion of the work the project team needs to
>     provide (contributing updates when major related happen in the code,
>     having a liaison, and a "checkup" at a date specified near the end
>     of the cycle). If there are any constraints about which projects
>     can apply, those should be documented, too. Maybe "independent"
>     projects (not following the release cycle) are not candidates, for
>     example.
>     The tag application process section should cover who can propose a
>     tag, and who needs to approve it. In this case, I would think the
>     project team PTL and docs PTL should both agree, after having the
>     conversation to ensure there is full understanding about the
>     expectations. It sounds a bit formal, but it shouldn't be a long
>     conversation in most cases and the structured process will help
>     reduce miscommunication.
>     After the tag is documented, the release team can add any dates to
>     the schedule and include reminders in the regular countdown emails.
>     That way we have one place for folks to go to keep up with the cycle
>     rhythm.
>     I can help with an initial draft of the tag document, if you like.
>     Doug
> Doug – this would be really helpful. Thank you :) it also makes sense that we 
> sync up with a similar process to the I18n team.
> I would just like to check rather than assume, this would be a TC tag? 
> https://governance.openstack.org/tc/reference/tags/index.html 
> Alex

Yes, that's right. Maybe you and I can work on the first draft in
an etherpad, and then you can submit the patch? I set this one up based
on the tag-template.txt file in the governance repository:



OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe

Reply via email to