[openstack-dev] [docs][all][ptl] doc-migration status

Alexandra Settle a.settle at outlook.com
Tue Jul 4 09:55:35 UTC 2017

Just to add to this, today I have spent some time going through and abandoning patches that were against the master branch for openstack-manuals and I have backported those applicable to Ocata.

If anyone has patches against the master branch that are addressing a bug/fix/enhancement in the install, networking, config ref, CLI ref, or admin guides – please abandon and move to relevant repo.

Thanks everyone for all your hard work! This has been a massive success (so far) as a result of everyone pooling together (

On 7/3/17, 3:34 PM, "Doug Hellmann" <doug at doughellmann.com> wrote:

    After a busy week last week, we made some good progress with the
    documentation migration project. We still have quite a few repositories
    that haven't been started, though, so please keep working. If you
    need assistance preparing or reviewing the patches, let us know
    with a follow-up email to this thread or by asking in #openstack-docs.
    Because we still have a lot of work to do in the openstack-manuals
    repo, the documentation team has started landing patches to remove
    the content that is being migrated into project repositories. If
    you have not yet started your migration, check out the commit tagged
    "before-migration" in openstack-manuals to find the content to be
    As part of this work today we have also prepared a patch to move
    all remaining projects to the new documentation build jobs. This
    will cause any content from doc/source to be published to
    docs.o.o/$project/latest instead of docs.o.o/developer/$project.
    Project teams still need to reorganize this content as described
    in the spec to ensure the automatically generated landing pages
    point to the correct URLs.
    We need to complete this migration work before creating stable
    branches, to avoid having to backport the documentation changes.
    Over the course of last week, we had a few questions about the
    directions and about reviews.
    1. Please use the gerrit topic "doc-migration" for all of the patches
    related to this work. We are monitoring the available changes by
    using that topic in queries, and we won't see your patches to help
    with reviews if you use another topic. Tying your patch to the
    blueprint using "Blueprint: doc-migration" will set the topic of
    the patch to "bp/doc-migration", and the patches will not appear
    in the query results.
    2. Please work on the steps in the order given. We have had quite
    a few patches that only apply the new theme, without reorganizing
    the content for the projects. These projects will not be linked
    properly from the templated landing pages, so your users will have
    trouble finding your documentation.
    3. Only official OpenStack projects, under TC governance, should
    use the openstackdocs theme. Projects publishing their documentation
    to readthedocs.org or other sites should not use the theme, and do
    not need to take any of the other migration steps.
    4. Reviewers, please prioritize landing the intiial content import
    and ask for follow-up patches to fix issues, unless the content is
    just absolutely wrong. Whitespace issues, typos, etc. should all
    be fixed after the initial import of the content created by the
    documentation team is complete.
    5. Projects with a "deployment guide" instead of "install guide"
    need to make sure they are using the openstackdocs theme and to
    update the organization of the rest of their content. The deployment
    guide should stay where it is, for now.
    6. We've had a couple of cases where multiple people did the same
    work because neither put their name next to the repository in the
    list on https://etherpad.openstack.org/p/doc-migration-tracking.
    We have plenty of this work to go around! Please use the etherpad
    to sign up for the repo you are going to work on *before* starting
    to write patches, so that we can avoid duplicating effort!
    If you run into trouble or have other questions, please follow-up
    here or ping us in the #openstack-doc IRC channel on Freenode.
    OpenStack Development Mailing List (not for usage questions)
    Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe

More information about the OpenStack-dev mailing list