From 22bee2f59752696fff83677889691e422416fb61 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Tue, 26 Sep 2017 13:06:42 -0400 Subject: [PATCH] update the retention policy for queens Replace the old archiving spec, which was never implemented, with a new one for queens describing the updated retention policy. Change-Id: I6e6fa98c577aa0d95af0824b763ce6a3b4728cbe Signed-off-by: Doug Hellmann --- doc/source/index.rst | 9 + specs/pike/archiving.rst | 124 ------------- specs/queens/retention-policy.rst | 296 ++++++++++++++++++++++++++++++ 3 files changed, 305 insertions(+), 124 deletions(-) delete mode 100644 specs/pike/archiving.rst create mode 100644 specs/queens/retention-policy.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index d465aa3..8e2a0ff 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -4,6 +4,15 @@ Documentation Program Specifications ==================================== +Queens approved specs +===================== + +.. toctree:: + :glob: + :maxdepth: 1 + + specs/queens/* + Pike approved specs ====================== diff --git a/specs/pike/archiving.rst b/specs/pike/archiving.rst deleted file mode 100644 index af22bbb..0000000 --- a/specs/pike/archiving.rst +++ /dev/null @@ -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: ``_ -* OpenStack "End of Life" support policy: ``_ -* OpenStack User Survey snapshot results, October 2016: - ``_ -* This conversation was triggered by: - ``_ and - ``_ -* Mailing list conversation: - ``_ -* Meeting discussion: - ``_ diff --git a/specs/queens/retention-policy.rst b/specs/queens/retention-policy.rst new file mode 100644 index 0000000..f3607e6 --- /dev/null +++ b/specs/queens/retention-policy.rst @@ -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. `__ + + 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) + `__ + * `July 2017 (dev list) + `__ + * `August 2017 (dev list) + `__ + +* `Notes from discussion at the Queens PTG + `__ + +* `Old "Archiving" spec + `__ + +* `Old "Archiving" blueprint + `__