@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Document that tagging something with a project never affects visibility
Summary: Fixes T10144.
Test Plan: (-O.O-)
Reviewers: chad
Reviewed By: chad
Maniphest Tasks: T10144
Differential Revision: https://secure.phabricator.com/D15107
+109
-1
+109
-1
src/docs/user/userguide/projects.diviner
+109
-1
src/docs/user/userguide/projects.diviner
···
8
8
9
9
NOTE: This document is only partially complete.
10
10
11
-
Phabricator projects are flexible groups of users and objects.
11
+
Phabricator projects are flexible, general-purpose groups of objects that you
12
+
can use to organize information. Projects have some basic information like
13
+
a name and an icon, and may optionally have members.
14
+
15
+
For example, you can create projects to provide:
16
+
17
+
- **Organization**: Create a project to represent a product or initative,
18
+
then use it to organize related work.
19
+
- **Groups**: Create a project to represent a group of people (like a team),
20
+
then add members of the group as project members.
21
+
- **Tags**: To create a tag, just create a project without any members. Then
22
+
tag anything you want.
23
+
- **Access Control Lists**: Add members to a project, then restrict the
24
+
visibility of objects to members of that project. See "Understanding
25
+
Policies" below to understand how policies and projects interact in
26
+
more detail.
12
27
28
+
Understanding Policies
29
+
======================
30
+
31
+
An important rule to understand about projects is that **adding or removing
32
+
projects to an object never affects who can see the object**.
33
+
34
+
For example, if you tag a task with a project like {nav Backend}, that does not
35
+
change who can see the task. In particular, it does not limit visibility to
36
+
only members of the "Backend" project, nor does it allow them to see it if they
37
+
otherwise could not. Likewise, removing projects does not affect visibility.
38
+
39
+
If you're familiar with other software that works differently, this may be
40
+
unexpected, but the rule in Phabrictor is simple: **adding and removing
41
+
projects never affects policies.**
42
+
43
+
Note that you //can// write policy rules which restrict capabilities to members
44
+
of a specific project or set of projects, but you do this by editing an
45
+
object's policies and adding rules based on project membership, not by tagging
46
+
or untagging the object with projects.
47
+
48
+
To manage who can seen an object, use the object's policy controls,
49
+
Spaces (see @{article:Spaces User Guide}) and Custom Forms
50
+
(see @{article:User Guide: Customizing Forms}).
51
+
52
+
For more details about rationale, see "Policies In Depth", below.
13
53
14
54
Joining Projects
15
55
================
···
93
133
**Hide Unused Items**: If you have a project which you don't expect to have
94
134
members or won't have a workboard, you can hide these items to streamline the
95
135
menu.
136
+
137
+
138
+
Policies In Depth
139
+
=================
140
+
141
+
As discussed above, adding and removing projects never affects who can see an
142
+
object. This is an explicit product design choice aimed at reducing the
143
+
complexity of policy management.
144
+
145
+
Phabricator projects are a flexible, general-purpose, freeform tool. This is a
146
+
good match for many organizational use cases, but a very poor match for
147
+
policies. It is important that policies be predictable and rigid, because the
148
+
cost of making a mistake with policies is high (inadvertent disclosure of
149
+
private information).
150
+
151
+
In Phabricator, each object (like a task) can be tagged with multiple projects.
152
+
This is important in a flexible organizational tool, but is a liability in a
153
+
policy tool.
154
+
155
+
If each project potentially affected visibility, it would become more difficult
156
+
to predict the visibility of objects and easier to make mistakes with policies.
157
+
There are different, reasonable expectations about how policies might be
158
+
affected when tagging objects with projects, but these expectations are in
159
+
conflict, and different users have different expectations. For example:
160
+
161
+
- if a user adds a project like {nav Backend} to a task, their intent
162
+
might be to //open// the task up and share it with the "Backend" team;
163
+
- if a user adds a project like {nav Security Vulnerability} to a task,
164
+
their intent might be to //close// the task down and restrict it to just
165
+
the security team;
166
+
- if a user adds a project like {nav Easy Starter Task} to a task, their
167
+
intent might be to not affect policies at all;
168
+
- if a user adds {nav Secret Inner Council} to a task already tagged with
169
+
{nav Security Vulnerability}, their intent might be to //open// the task
170
+
to members of //either// project, or //close// the task to just members of
171
+
//both// projects;
172
+
- if a user adds {nav Backend} to a task already tagged with
173
+
{nav Security Vulnerability}, their intent is totally unclear;
174
+
- in all cases, users may be adding projects purely to organize objects
175
+
without intending to affect policies.
176
+
177
+
We can't distinguish between these cases without adding substantial complexity,
178
+
and even if we made an attempt to navigate this it would still be very
179
+
difficult to predict the effect of tagging an object with multiple
180
+
policy-affecting projects. Users would need to learn many rules about how these
181
+
policy types interacted to predict the policy effects of adding or removing a
182
+
project.
183
+
184
+
Because of the implied complexity, we almost certainly could not prevent some
185
+
cases where a user intends to take a purely organizational action (like adding
186
+
a {nav Needs Documentation} tag) and accidentally opens a private object to a
187
+
wide audience. The policy system is intended to make these catastrophically bad
188
+
cases very difficult, and allowing projects to affect policies would make these
189
+
mistakes much easier to make.
190
+
191
+
We believe the only reasonable way we could reduce ambiguity and complexity is
192
+
by making project policy actions explicit and rule-based. But we already have a
193
+
system for explicit, rule-based management of policies: the policy system. The
194
+
policy tools are designed for policy management and aimed at making actions
195
+
explicit and mistakes very difficult.
196
+
197
+
Many of the use cases where project-based access control seems like it might be
198
+
a good fit can be satisfied with Spaces instead (see @{article:Spaces User
199
+
Guide}). Spaces are explicit, unambiguous containers for groups of objects with
200
+
similar policies.
201
+
202
+
Form customization also provides a powerful tool for making many policy
203
+
management tasks easier (see @{article:User Guide: Customizing Forms}).