Merge "update the retention policy for queens"
This commit is contained in:
Zuul
Gerrit Code Review
commit
8146272d0e
|
|
@ -4,6 +4,15 @@
|
|||
Documentation Program Specifications
|
||||
====================================
|
||||
|
||||
Queens approved specs
|
||||
=====================
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
specs/queens/*
|
||||
|
||||
Pike approved specs
|
||||
======================
|
||||
|
||||
|
|
|
|||
|
|
@ -1,124 +0,0 @@
|
|||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
=================================================
|
||||
Archiving old documentation on docs.openstack.org
|
||||
=================================================
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
As of the time of drafting, the docs.openstack.org site retention policy is
|
||||
to publish the current release (Newton), plus two previous releases (Mitaka
|
||||
and Liberty). The retention policy was initially designed to match the "End
|
||||
of Life" support policy that project branches adhere to, which is documented
|
||||
as indicating stable branches (see References). Because the project code
|
||||
would not be supported, the docs were removed from the docs site, to match
|
||||
the project code branch strategy.
|
||||
|
||||
According to the last User Survey (see References), 9% of production OpenStack
|
||||
installations were still running Icehouse, 17% were running Juno, and 40% were
|
||||
running Kilo.
|
||||
|
||||
This would indicate that a significant number of users are relying on
|
||||
documentation that could potentially disappear in accordance with our current
|
||||
retention policy.
|
||||
|
||||
Historical note: When the documentation pages were created in 2010, they were
|
||||
hosted on Rackspace Cloud Sites without a clear retention policy, which
|
||||
resulted in a large number of unmanaged files over many years. The docs.o.o
|
||||
site was the largest site on Cloud Sites at the time, which resulted in Cloud
|
||||
Sites specifically asking us to remove old content. Change in hosting provider
|
||||
was eventually enforced on the team by the sale of Cloud Sites to Liquid Web
|
||||
in 2016, and the site is now hosted on internal OpenStack infrastructure, and
|
||||
the current retention policy was decided upon at the Barcelona Summit in
|
||||
October 2016.
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
* At every new release, the release becoming EOL'd is moved to a read-only
|
||||
archive folder (this can be completed with a script, TBD).
|
||||
* The archive folder is made available online for people to download the
|
||||
branch they require as a tar.gz file.
|
||||
* The archive folder should be accessible from the openstack-manuals repo,
|
||||
and delivered publicly from the docs.openstack.org site.
|
||||
* Note somewhere obvious that documents in the archive are not editable, and
|
||||
bugs raised against them will be closed WONTFIX.
|
||||
* Develop a procedure for taking a certain git history SHA and creating the
|
||||
documentation locally. Write this up in the Contributor Guide.
|
||||
|
||||
Notes
|
||||
-----
|
||||
|
||||
* This solution would cover all documentation in /$EOLRELEASE on
|
||||
docs.openstack.org, including /developer, in order to simplify the process.
|
||||
* This covers books that are already versioned (Install Guide, Config Ref,
|
||||
and CLI Ref), but could potentially be expanded to all books.
|
||||
* We will need to determine a threshold for deleting documentation from the
|
||||
archive permanently. This can be achieved through a community discussion.
|
||||
* All documentation history and tags will remain in the git repository, so it
|
||||
is always possible to checkout old versions, even if they are not published.
|
||||
* Can we do something like archive.openstack.org? Also, maybe a link to
|
||||
archives from the main docs site.
|
||||
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
* Maintain the status quo (Do nothing)
|
||||
* About a million other things
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
|
||||
Primary assignee:
|
||||
* Documentation team
|
||||
|
||||
Other contributors:
|
||||
* Lana Brindley (loquacities)
|
||||
* Alexandra Settle (asettle)
|
||||
* Brian Moss - Docs Tools (bmoss)
|
||||
* Anne Gentle (annegentle)
|
||||
|
||||
Work items
|
||||
----------
|
||||
|
||||
* Develop script for archiving (Brian & Infra)
|
||||
* Investigate the possibility of archiving only PDF versions (Brian & Infra)
|
||||
* Use Sphinxmark to watermark old versions, and add note about bugs
|
||||
(Brian & Tools)
|
||||
* Implementation
|
||||
* Document the procedure for restoring documentation from a git repo at a
|
||||
certain point-in-time (Anne)
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
* Infra assistance
|
||||
|
||||
Testing
|
||||
=======
|
||||
|
||||
Testing will follow the standard documentation review process.
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
* OpenStack supported releases: `<https://releases.openstack.org/>`_
|
||||
* OpenStack "End of Life" support policy: `<http://docs.openstack.org/project-team-guide/stable-branches.html/>`_
|
||||
* OpenStack User Survey snapshot results, October 2016:
|
||||
`<https://www.openstack.org/assets/survey/October2016SurveyReport.pdf>`_
|
||||
* This conversation was triggered by:
|
||||
`<https://bugs.launchpad.net/openstack-manuals/+bug/1658659>`_ and
|
||||
`<https://bugs.launchpad.net/openstack-manuals/+bug/1621685>`_
|
||||
* Mailing list conversation:
|
||||
`<http://lists.openstack.org/pipermail/openstack-docs/2017-January/009493.html>`_
|
||||
* Meeting discussion:
|
||||
`<http://eavesdrop.openstack.org/meetings/docteam/2017/docteam.2017-01-26-21.03.log.html>`_
|
||||
|
|
@ -0,0 +1,296 @@
|
|||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
==============================================
|
||||
Retention Policy for Published Documentation
|
||||
==============================================
|
||||
|
||||
https://blueprints.launchpad.net/openstack-manuals/+spec/retention-policy
|
||||
|
||||
The `2017 User survey`_ highlights the fact that many of our users are
|
||||
still deploying and otherwise working with versions of OpenStack for
|
||||
which upstream support is no longer available. These end-of-life
|
||||
versions are still clearly useful to some users, and to improve their
|
||||
experience we should continue to make the documentation for those
|
||||
releases available.
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
The current retention policy for published documentation calls for
|
||||
manuals to be removed from docs.openstack.org when the associated
|
||||
branches are marked "end of life" and closed. The older documentation
|
||||
has been removed from the site in the past for several reasons. In no
|
||||
particular order:
|
||||
|
||||
* **Content size**
|
||||
|
||||
The amount of content we were publishing was quite large for the
|
||||
hosting service being used at the time.
|
||||
|
||||
* **Search results**
|
||||
|
||||
* Removing older documentation was seen as reducing confusion
|
||||
because users searching without specifying a version number or
|
||||
series name would not encounter information that was out of date.
|
||||
|
||||
* Documentation for older releases, by virtue of having longer lived
|
||||
stable URLs, was appearing higher in search results than similar
|
||||
updated content for newer releases.
|
||||
|
||||
* **Support requests**
|
||||
|
||||
Bugs and support requests have been filed for versions of the
|
||||
documentation that will no longer be updated or fixed. This caused
|
||||
undue burden to the documentation team.
|
||||
|
||||
* **Build support**
|
||||
|
||||
After the stable branch for the documentation was closed, there was
|
||||
no longer a way to build and update the published
|
||||
documentation. This is not an issue with regard to content, but we
|
||||
have had at least one situation where there was a security issue for
|
||||
a cross-site-scripting attack that pointed out if we had similar
|
||||
problems in the future with dynamic aspects of the site for branches
|
||||
that could no longer be built, deleting the content may be the only
|
||||
action we could take. See commit
|
||||
de6289854e9a059d5a33075b6593e7f9cb3b4f2d in the
|
||||
clouddocs-maven-plugin repository for details (that repository is
|
||||
not indexed via gerrit or available via the cgit web UI for some
|
||||
reason).
|
||||
|
||||
We are updating this policy for two reasons:
|
||||
|
||||
1. According to the latest user survey at the time of this writing,
|
||||
around 60% of users running a version of OpenStack no longer
|
||||
supported upstream. These users are left without accurate
|
||||
documentation for the versions of software that they are deploying.
|
||||
|
||||
2. As part of the :doc:`../pike/os-manuals-migration` initiative, more
|
||||
of the actively maintained documentation is now managed by project
|
||||
teams outside of the ``openstack-manuals`` git repository.
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
The proposed change is to stop deleting all content from
|
||||
docs.openstack.org based on its age, or the age of the software to
|
||||
which it applies or the repository from which it was recovered.
|
||||
|
||||
We will also recover the admin guide, CLI reference, and user guide
|
||||
for Mitaka through Ocata. The admin guide is meant to be reusable
|
||||
between series, but that is only true when the underlying operating
|
||||
system does not change. Since it has changed in the past, we need to
|
||||
view the admin guide as series-specific *even when we do not change
|
||||
it*. The CLI reference and user guide for Mitaka use the old versions
|
||||
of the clients, and the options may have changed since then.
|
||||
|
||||
The Mitaka series was selected for several reasons.
|
||||
|
||||
1. It is the first series for which all of the documentation was
|
||||
managed using Sphinx, which is easier to install than the older
|
||||
tools and we have more knowledge throughout the community for
|
||||
working with Sphinx.
|
||||
|
||||
2. It also represents a sufficiently old version to be useful to a
|
||||
large number of users. The combination of utility and ease of
|
||||
updating makes Mitaka a good compromise point for starting the new
|
||||
retention policy.
|
||||
|
||||
3. Much of the project-specific documentation from the Mitaka release
|
||||
still exists on docs.openstack.org so it will be easy to link to
|
||||
it.
|
||||
|
||||
We will find other ways to mitigate the issues that motivated us to
|
||||
adopt the old policy of deleting end-of-life releases.
|
||||
|
||||
The documentation for end-of-life releases will still be frozen when
|
||||
the relevant stable branches are closed, so no updates will be
|
||||
made. This change should not significantly expand the maintenance
|
||||
burden or expectations of users.
|
||||
|
||||
* **Content size**
|
||||
|
||||
We have already migrated docs.openstack.org off of the CloudSites
|
||||
hosting service to a standard web server with a large
|
||||
filesystem. The amount of content we are publishing is no longer a
|
||||
significant issue.
|
||||
|
||||
* **Search results**
|
||||
|
||||
Given the number of users running older versions, our priorities for
|
||||
search results have changed. We *want* old versions to be available
|
||||
via search engines, assuming the user can easily determine whether
|
||||
the results they have found match their version or that they can
|
||||
navigate between versions quickly.
|
||||
|
||||
We will continue to experiment with search engine optimization
|
||||
techniques to have unqualified searches like "installing nova" show
|
||||
newer results. That work will have its own spec, to be created by
|
||||
the team that takes on the task.
|
||||
|
||||
We can make navigating between series-specific docs easy by taking
|
||||
advantage of the ``earliest_published_series`` `configuration option
|
||||
for the
|
||||
theme. <https://docs.openstack.org/openstackdocstheme/latest/>`__
|
||||
|
||||
We will also update the documentation theme to include a watermark
|
||||
or "badge" clearly indicating when content is considered old and
|
||||
especially when it is no longer maintained. These markers need to be
|
||||
built outside of the documentation itself so they can be updated
|
||||
independently, without patching the docs or adding steps to the
|
||||
stable branch EOL process. The plan discussed at the PTG was based
|
||||
on SVG files built from the openstack-manuals repository and
|
||||
included into published pages by the ``openstackdocstheme``. More
|
||||
details need to be worked out, and that work will involve its own
|
||||
spec to follow this one.
|
||||
|
||||
* **Support requests**
|
||||
|
||||
Project teams are now responsible for project-specific
|
||||
documentation. Bugs and support requests that come in to the
|
||||
documentation team can be triaged and reassigned to project teams as
|
||||
needed. Anything related to documentation that is no longer
|
||||
supported should be treated the same way as bug reports for
|
||||
unsupported code (closed "wontfix").
|
||||
|
||||
* **Build support**
|
||||
|
||||
Because we are not extending the supported lifetime for stable
|
||||
branches and the documentation they contain, the only reasons to
|
||||
need to build the docs are if we lose the data on the web server or
|
||||
if there is another security issue. After a branch is closed, no
|
||||
more updates to the documentation for that branch need to be
|
||||
considered.
|
||||
|
||||
While we do not want to downplay the seriousness of potential issues
|
||||
with cross-site scripting or JavaScript CVEs, we also do not want to
|
||||
over-emphasize the likelihood of such issues coming up. If such
|
||||
issues do arise, we will work on a resolution at that time. In a
|
||||
worst-case scenario where restoring stable branches and changing the
|
||||
builds does not work, and manual updates of the affected files are
|
||||
not possible, we can delete the bad content. Any decision about the
|
||||
best course of action will be made at the time by the people
|
||||
actively working on the problem.
|
||||
|
||||
Similarly, if we experience a loss of data on the web server and
|
||||
need to rebuild content, the people managing the recovery can
|
||||
develop a plan when needed.
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
#. Do nothing.
|
||||
|
||||
This option is not appealing because we have had clear and loud
|
||||
requests from users to help them in this area.
|
||||
|
||||
#. Suggest that users build local copies of the documentation for old
|
||||
releases.
|
||||
|
||||
Some users have resorted to trying to build their own internal
|
||||
copies of the documentation to continue to manage their
|
||||
deployments. They have found issues with the documentation at the
|
||||
``$series-eol`` tags no longer building properly because external
|
||||
references to things like sample files in git repositories are not
|
||||
present.
|
||||
|
||||
#. Create ``docfixes`` branches, similar to the ``driverfixes``
|
||||
branches used by project teams to allow vendors to collaborate on
|
||||
patches to drivers after a version of the software has been marked
|
||||
EOL. The ``docfixes`` branches would be allowed to build only the
|
||||
documentation and update the published content on
|
||||
docs.openstack.org (they would not be used for new releases of
|
||||
software or code patches not related to documentation).
|
||||
|
||||
Without a significant number of contributors to review and manage
|
||||
pages in these branches, it seems unlikely that we would see any
|
||||
benefit from keeping them open. If the contributions to the
|
||||
existing stable branches increase, we can reconsider this option in
|
||||
the future.
|
||||
|
||||
#. Archive the content in non-indexed formats such as tarballs.
|
||||
|
||||
The old archival spec approved for Pike but never implemented
|
||||
requires much more manual work and active management of old
|
||||
content. Simply leaving the content in place on the web server is
|
||||
more sustainable with a small documentation team.
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
|
||||
Primary assignees:
|
||||
|
||||
* dhellmann
|
||||
|
||||
Other contributors:
|
||||
|
||||
* pkovar
|
||||
|
||||
Work Items
|
||||
----------
|
||||
|
||||
* Restore the stable/mitaka version of the admin, cli, and user guides
|
||||
are published using series-specific URLs. (dhellmann)
|
||||
|
||||
* Create a new ``stable/mitaka`` branch.
|
||||
* Update the build scripts so the manuals are published to
|
||||
series-specific URLs.
|
||||
* Add appropriate redirects.
|
||||
* Re-close the branch.
|
||||
|
||||
* Update the stable/ocata branch of openstack/openstack-manuals to
|
||||
build the admin, cli, and user guides using series-specific
|
||||
URLs. (*owner needed*)
|
||||
|
||||
* Update the build scripts so the manuals are published to
|
||||
series-specific URLs.
|
||||
* Add appropriate redirects.
|
||||
* Update the stable/newton branch of openstack/openstack-manuals to
|
||||
link to the Ocata versions of the admin, cli, and user guides.
|
||||
|
||||
* Write a spec for the version "badges" and implement the appropriate
|
||||
changes. (*owner needed*)
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
None
|
||||
|
||||
Testing
|
||||
=======
|
||||
|
||||
Old documents will be recovered as-is, and only changes needed to
|
||||
update the publication locations and ensure the builds work will be
|
||||
allowed.
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
* `2017 User survey`_
|
||||
|
||||
.. _2017 User survey: http://superuser.openstack.org/articles/2017-openstack-user-survey-insights/
|
||||
|
||||
* Mailing list threads
|
||||
|
||||
* `July 2017 (docs list)
|
||||
<http://lists.openstack.org/pipermail/openstack-docs/2017-July/thread.html#10069>`__
|
||||
* `July 2017 (dev list)
|
||||
<http://lists.openstack.org/pipermail/openstack-dev/2017-July/thread.html#120254>`__
|
||||
* `August 2017 (dev list)
|
||||
<http://lists.openstack.org/pipermail/openstack-dev/2017-August/thread.html#120541>`__
|
||||
|
||||
* `Notes from discussion at the Queens PTG
|
||||
<https://etherpad.openstack.org/p/docs-i18n-ptg-queens>`__
|
||||
|
||||
* `Old "Archiving" spec
|
||||
<http://git.openstack.org/cgit/openstack/docs-specs/commit/?id=4ce480f4e29d8514a8b01acbe8157d84ed731d04>`__
|
||||
|
||||
* `Old "Archiving" blueprint
|
||||
<https://blueprints.launchpad.net/openstack-manuals/+spec/archiving>`__
|
||||
Loading…
Reference in New Issue