Skip to content

Investigate alternatives to current docs.securedrop.org versioning #3279

@eloquence

Description

@eloquence

If you visit https://docs.securedrop.org/ for the first time, you are currently redirected to https://docs.securedrop.org/en/release-0.6/ -- this is problematic; it means that any links circulated from browsing become outdated very quickly.

This was implemented as a workaround to the problem that stable points to the latest release tag, and cutting a new release just to correct an error for the docs in a given SecureDrop release isn't workable.

What are the alternatives?

  • Can stable point to the latest release branch, so we can cherry-pick docs updates without outdated URLs? Per @redshiftzero I don't believe this is possible, and the docs say "If you have at least one active tag, tags will take preference over branches when selecting the stable version." (http://docs.readthedocs.io/en/latest/versions.html)
  • If not, can a permanent name like production be used for pointing to the current release branch, and be used as the default?
  • If not, would it make sense to build docs from its own repo? Tags there could parallel SD development without matching it precisely.

If none of these are good options, I would suggest defaulting back to stable for first-time visits to docs.securedrop.org regardless, as it's a safer default choice than redirecting people to URLs that will get stale within weeks.

It's important to note that latest links are dangerous for any uses except development. For example, they will include invalid version strings like "0.7.0~rc1" in the instructions for admins:
https://docs.securedrop.org/en/latest/set_up_admin_tails.html

For this reason, the use of latest for circulating updated troubleshooting docs and the like is inadvisable.

User Stories

  • As a SecureDrop admin, I want to get documentation that is accurate and up-to-date, so that I don't follow outdated instructions.

  • As a SecureDrop admin, I don't want to get information that only applies to the development version of SecureDrop.

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs/discussionqueued up for discussion at future team meeting. Use judiciously.

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions