Skip to content

Commit 0b4eadd

Browse files
stsewdstsewd
authored
Merge pull request #6194 from stsewd/design-doc-privacy-levels
Design doc for privacy levels
2 parents 6394d6d + b9cc130 commit 0b4eadd

File tree

1 file changed

+230
-0
lines changed

1 file changed

+230
-0
lines changed

‎docs/development/design/privacy-levels.rst

+230
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
Privacy Levels
2+
==============
3+
4+
This document describes how to handle and unify privacy levels
5+
on the community and commercial version of Read the Docs.
6+
7+
Current state
8+
-------------
9+
10+
Currently, we have three privacy levels for projects and versions:
11+
12+
#. Public
13+
#. Private
14+
#. Protected (currently hidden)
15+
16+
These levels of privacy aren't clear and bring confusion to our users.
17+
Also, the private level doesn't makes sense on the community site,
18+
since we only support public projects.
19+
20+
Places where we use the privacy levels are:
21+
22+
- On serving docs
23+
- Footer
24+
- Dashboard
25+
26+
Project level privacy
27+
---------------------
28+
29+
Project level privacy was meant to control the dashboard visibility.
30+
31+
This privacy level brings to confusion when users want to make a version public.
32+
We should remove all the project privacy levels.
33+
34+
For the community site the dashboard would be always visible,
35+
and for the commercial site, the dashboard would be always hidden.
36+
37+
The project privacy level is also used to serve the ``404.html`` page,
38+
show ``robots.txt``, and show ``sitemap.xml``.
39+
The privacy level from versions should be used instead.
40+
41+
Some other ideas about keeping the privacy level is to dictate the default version level of new versions,
42+
but removing all other logic related to this privacy level.
43+
This can be (or is going to be) possible with automation rules,
44+
so we can just remove the field.
45+
46+
Version level privacy
47+
---------------------
48+
49+
Version level privacy is mainly used to restrict access to documentation.
50+
For public level, everyone can access to the documentation.
51+
For private level, only users that are maintainers or that belong to a team with access
52+
(for the commercial site)
53+
can access to the documentation.
54+
55+
The protected privacy level was meant to hide versions from listings and search.
56+
For the community site these versions are treated like public versions,
57+
and on the commercial site they are treated like private.
58+
59+
The protected privacy level is currently hidden.
60+
To keep the behavior of hiding versions from listings and search,
61+
a new field should be added to the Version model and forms: ``hidden`` (`#5321 <https://github.com/readthedocs/readthedocs.org/issues/5321>`__).
62+
The privacy level (public or private) would be respected to determine access to the documentation.
63+
64+
For the community site, the privacy level would be public and can't be changed.
65+
66+
The default privacy level of new versions for the commercial site would be ``private``
67+
(this is the ``DEFAULT_PRIVACY_LEVEL`` setting).
68+
69+
Footer
70+
------
71+
72+
The footer is used to display not hidden versions that the current user has access to.
73+
74+
For the community site no changes are required on the footer.
75+
76+
For the commercial site we use the project level privacy to decide if show or not
77+
links to the project's dashboard: downloads, project home, and builds.
78+
Given that the project privacy level would be removed (and the dashboard is always under login),
79+
those links would never be shown, except for admin users (owners or from a team with admin access)
80+
since they are the only ones allowed to make changes on the project.
81+
82+
Overview
83+
--------
84+
85+
For the community site:
86+
87+
- The project's dashboard is visible to all users.
88+
- All versions are always public.
89+
- The footer shows links to the project's dashboard (build, downloads, home) to all users.
90+
- Only versions with ``hidden = False`` are listed on the footer and appear on search results.
91+
- If a project has a `404.html` file on the default version, it's served.
92+
- If a project has a ``robots.txt`` file on the default version, it's served.
93+
- A ``sitemap.xml`` file is always served.
94+
95+
For the commercial site:
96+
97+
- The project's dashboard is visible to only users that have read permission over the project.
98+
- The footer shows links to the project's dashboard (build, downloads, home) to only admin users.
99+
- Only versions with ``hidden = False`` are listed on the footer and appear on search results.
100+
- If a project has a ``404.html`` file on the default version, it's served if the user has permission over that version.
101+
- If a project has a ``robots.txt`` file on the default version, it's served if the user has permission over that version.
102+
- A ``sitemap.xml`` file is served if the user has at least one public version.
103+
And it will only list public versions.
104+
105+
Migration
106+
---------
107+
108+
To differentiate between allowing or not privacy levels,
109+
we need to add a setting ``RTD_ALLOW_PRIVACY_LEVELS`` (``False`` by default).
110+
111+
For the community and commercial site, we need to:
112+
113+
- Remove/change code that depends on the project's privacy level.
114+
Use the global setting ``RTD_ALLOW_PRIVACY_LEVELS`` and default version's privacy level instead.
115+
116+
- Display robots.txt
117+
- Serve 404.html page
118+
- Display sitemap.xml
119+
- Querysets
120+
121+
- Remove `Project.privacy_level` field
122+
- Migrate all protected versions to have the attribute ``hidden = True`` (data migration),
123+
and set their privacy level to public for the community site and private for the commercial site.
124+
- Change all querysets used to list versions on the footer and on search to use the ``hidden`` attribute.
125+
- Update docs
126+
127+
For the community site:
128+
129+
- Hide all privacy level related settings from the version form.
130+
- Don't expose privacy levels on API v3.
131+
- Mark all versions as public.
132+
133+
For the commercial site:
134+
135+
- Always hide the dashboard
136+
- Show links to the dashboard (downloads, builds, project home) on the footer only to admin users.
137+
138+
Upgrade path overview
139+
---------------------
140+
141+
Community site
142+
##############
143+
144+
The default privacy level for the community site is public for versions and the dashboard is always public.
145+
146+
Public project (community)
147+
~~~~~~~~~~~~~~~~~~~~~~~~~~
148+
149+
- Public version:
150+
Normal use case, no changes required.
151+
- Protected version:
152+
Users didn't want to list this version on the footer,
153+
but also not deactivate it.
154+
We can do a data migration of those versions to the new ``hidden`` setting and make them public.
155+
- Private version:
156+
Users didn't want to show this version to their users yet or they were testing something.
157+
This can be solved with the pull request builder feature and the ``hidden`` setting.
158+
We migrate those to public with the ``hidden`` setting.
159+
If we are worried about leaking anything from the version, we can email users before doing the change.
160+
161+
Protected project (community)
162+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
163+
164+
Protected projects are not listed publicly.
165+
Probably users were hosting a WIP project,
166+
or personal public project.
167+
A public project should work for them,
168+
as we are removing listing all projects publicly (except for search).
169+
170+
The migration path for versions of protected projects is the same as a public project.
171+
172+
Private project (community)
173+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
174+
175+
Probably these users want to use our enterprise solution instead.
176+
Or they were hosting a personal project.
177+
178+
The migration path for versions of private projects is the same as a public project.
179+
180+
If we are worried about leaking anything from the dashboard or build page,
181+
we can email users before doing the change.
182+
183+
Commercial site
184+
###############
185+
186+
The default privacy level for the commercial site is private for versions and the dashboard is show only to admin users.
187+
188+
Private project (commercial)
189+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
190+
191+
- Private version:
192+
Normal usa case, not changes required.
193+
- Protected version:
194+
Users didn't want to list this version on the footer,
195+
but also not deactivate it. This can be solved by using the new ``hidden`` setting.
196+
We can do a data migration of those versions to the new ``hidden`` setting and make them private.
197+
- Public version:
198+
User has private code, but want to make public their docs.
199+
No changes required.
200+
201+
Protected project (commercial)
202+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
203+
204+
I can't think of a use case for protected projects,
205+
since they aren't listed publicly on the commercial site.
206+
207+
The migration path for versions of protected projects is the same as a private project.
208+
209+
Public project (commercial)
210+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
211+
212+
Currently we show links back to project dashboard if the project is public,
213+
which probably users shouldn't see.
214+
With the implementation of this design doc,
215+
public versions don't have links to the project dashboard (except for admin users) and the dashboard is always under login.
216+
217+
- Private versions:
218+
Users under the organization can see links to the dashboard.
219+
Not changes required.
220+
- Protected versions:
221+
Users under the organization can see links to the dashboard.
222+
We can do a data migration of those versions to the new ``hidden`` setting and make them private.
223+
- Public versions:
224+
All users can see links to the dashboard.
225+
Probably they have an open source project,
226+
but they still want to manage access using the same teams of the organization.
227+
Not changes are required.
228+
229+
A breaking change here is:
230+
users outside the organization would not be able to see the dashboard of the project.

0 commit comments

Comments
 (0)