Adding Archiving spec

Based on email thread and meeting conversation, adding a spec to
address the requirement to archive old content, and make it available
to users on older versions of OpenStack. Also adds Pike to specs index.

Change-Id: I7dffceddb040137b0f1448ba4baebcb5c5dfc9d9
blueprint: archiving
This commit is contained in:
Lana Brindley 2017-01-27 13:57:23 +10:00
parent e2abbcd68b
commit 4ce480f4e2
2 changed files with 133 additions and 0 deletions

View File

@ -4,6 +4,15 @@
Documentation Program Specifications
====================================
Pike approved specs
======================
.. toctree::
:glob:
:maxdepth: 1
specs/pike/*
Ocata approved specs
======================

124
specs/pike/archiving.rst Normal file
View File

@ -0,0 +1,124 @@
..
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>`_