On 3/2/17, 4:42 PM, "Doug Hellmann" <d...@doughellmann.com> wrote:
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
Perfect! I’ll get on this and involve the doc community to ensure we’re getting
everything down :)
Appreciate your support and assistance, 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
__________________________________________________________________________
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
