Privacy levels

This document describes how to handle and unify privacy levels on the community and commercial version of Read the Docs.

Current state

Currently, we have three privacy levels for projects and versions:

  1. Public

  2. Private

  3. Protected (currently hidden)

These levels of privacy aren’t clear and bring confusion to our users. Also, the private level doesn’t makes sense on the community site, since we only support public projects.

Places where we use the privacy levels are:

  • On serving docs

  • Footer

  • Dashboard

Project level privacy

Project level privacy was meant to control the dashboard visibility.

This privacy level brings to confusion when users want to make a version public. We should remove all the project privacy levels.

For the community site the dashboard would be always visible, and for the commercial site, the dashboard would be always hidden.

The project privacy level is also used to serve the 404.html page, show robots.txt, and show sitemap.xml. The privacy level from versions should be used instead.

Some other ideas about keeping the privacy level is to dictate the default version level of new versions, but removing all other logic related to this privacy level. This can be (or is going to be) possible with automation rules, so we can just remove the field.

Version level privacy

Version level privacy is mainly used to restrict access to documentation. For public level, everyone can access to the documentation. For private level, only users that are maintainers or that belong to a team with access (for the commercial site) can access to the documentation.

The protected privacy level was meant to hide versions from listings and search. For the community site these versions are treated like public versions, and on the commercial site they are treated like private.

The protected privacy level is currently hidden. To keep the behavior of hiding versions from listings and search, a new field should be added to the Version model and forms: hidden (#5321). The privacy level (public or private) would be respected to determine access to the documentation.

For the community site, the privacy level would be public and can’t be changed.

The default privacy level of new versions for the commercial site would be private (this is the DEFAULT_PRIVACY_LEVEL setting).

Overview

For the community site:

  • The project’s dashboard is visible to all users.

  • All versions are always public.

  • The footer shows links to the project’s dashboard (build, downloads, home) to all users.

  • Only versions with hidden = False are listed on the footer and appear on search results.

  • If a project has a 404.html file on the default version, it’s served.

  • If a project has a robots.txt file on the default version, it’s served.

  • A sitemap.xml file is always served.

For the commercial site:

  • The project’s dashboard is visible to only users that have read permission over the project.

  • The footer shows links to the project’s dashboard (build, downloads, home) to only admin users.

  • Only versions with hidden = False are listed on the footer and appear on search results.

  • If a project has a 404.html file on the default version, it’s served if the user has permission over that version.

  • If a project has a robots.txt file on the default version, it’s served if the user has permission over that version.

  • A sitemap.xml file is served if the user has at least one public version. And it will only list public versions.

Migration

To differentiate between allowing or not privacy levels, we need to add a setting RTD_ALLOW_PRIVACY_LEVELS (False by default).

For the community and commercial site, we need to:

  • Remove/change code that depends on the project’s privacy level. Use the global setting RTD_ALLOW_PRIVACY_LEVELS and default version’s privacy level instead.

    • Display robots.txt

    • Serve 404.html page

    • Display sitemap.xml

    • Querysets

  • Remove Project.privacy_level field

  • Migrate all protected versions to have the attribute hidden = True (data migration), and set their privacy level to public for the community site and private for the commercial site.

  • Change all querysets used to list versions on the footer and on search to use the hidden attribute.

  • Update docs

For the community site:

  • Hide all privacy level related settings from the version form.

  • Don’t expose privacy levels on API v3.

  • Mark all versions as public.

For the commercial site:

  • Always hide the dashboard

  • Show links to the dashboard (downloads, builds, project home) on the footer only to admin users.

Upgrade path overview

Community site

The default privacy level for the community site is public for versions and the dashboard is always public.

Public project (community)

  • Public version: Normal use case, no changes required.

  • Protected version: Users didn’t want to list this version on the footer, but also not deactivate it. We can do a data migration of those versions to the new hidden setting and make them public.

  • Private version: Users didn’t want to show this version to their users yet or they were testing something. This can be solved with the pull request builder feature and the hidden setting. We migrate those to public with the hidden setting. If we are worried about leaking anything from the version, we can email users before doing the change.

Protected project (community)

Protected projects are not listed publicly. Probably users were hosting a WIP project, or personal public project. A public project should work for them, as we are removing listing all projects publicly (except for search).

The migration path for versions of protected projects is the same as a public project.

Private project (community)

Probably these users want to use our enterprise solution instead. Or they were hosting a personal project.

The migration path for versions of private projects is the same as a public project.

If we are worried about leaking anything from the dashboard or build page, we can email users before doing the change.

Commercial site

The default privacy level for the commercial site is private for versions and the dashboard is show only to admin users.

Private project (commercial)

  • Private version: Normal usa case, not changes required.

  • Protected version: Users didn’t want to list this version on the footer, but also not deactivate it. This can be solved by using the new hidden setting. We can do a data migration of those versions to the new hidden setting and make them private.

  • Public version: User has private code, but want to make public their docs. No changes required.

Protected project (commercial)

I can’t think of a use case for protected projects, since they aren’t listed publicly on the commercial site.

The migration path for versions of protected projects is the same as a private project.

Public project (commercial)

Currently we show links back to project dashboard if the project is public, which probably users shouldn’t see. With the implementation of this design doc, public versions don’t have links to the project dashboard (except for admin users) and the dashboard is always under login.

  • Private versions: Users under the organization can see links to the dashboard. Not changes required.

  • Protected versions: Users under the organization can see links to the dashboard. We can do a data migration of those versions to the new hidden setting and make them private.

  • Public versions: All users can see links to the dashboard. Probably they have an open source project, but they still want to manage access using the same teams of the organization. Not changes are required.

A breaking change here is: users outside the organization would not be able to see the dashboard of the project.