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: https://etherpad.openstack.org/p/doc-managed-tag Doug __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
