@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
Add some documentation for Spaces
Summary: Ref T8449. Flesh out the documentation a bit.
Test Plan: Reading.
Reviewers: btrahan
Reviewed By: btrahan
Subscribers: epriestley
Maniphest Tasks: T8449
Differential Revision: https://secure.phabricator.com/D13248
+142
+142
src/docs/user/userguide/spaces.diviner
+142
src/docs/user/userguide/spaces.diviner
···
8
8
9
9
IMPORTANT: Spaces is a prototype application.
10
10
11
+
The Spaces application makes it easier to manage large groups of objects which
12
+
share the same access policy. For example:
13
+
14
+
- An organization might make a Space for a project in order to satisfy a
15
+
contractual obligation to limit access, even internally.
16
+
- An open source organization might make a Space for work related to
17
+
internal governance, to separate private and public discussions.
18
+
- A contracting company might make Spaces for clients, to separate them from
19
+
one another.
20
+
- A company might create a Space for consultants, to give them limited
21
+
access to only the resources they need to do their work.
22
+
- An ambitious manager might create a Space to hide her team's work from her
23
+
enemies at the company, that she might use the element of surprise to later
24
+
expand her domain.
25
+
26
+
Phabricator's access control policies are generally powerful enough to handle
27
+
these use cases on their own, but applying the same policy to a large group
28
+
of objects requires a lot of effort and is error-prone.
29
+
30
+
Spaces build on top of policies and make it easier and more reliable to
31
+
configure, review, and manage groups of objects with similar policies.
32
+
33
+
34
+
Creating Spaces
35
+
=================
36
+
37
+
Spaces are optional, and are inactive by default. You don't need to configure
38
+
them if you don't plan to use them. You can always set them up later.
39
+
40
+
To activate Spaces, you need to create at least two spaces. Create spaces from
41
+
the web UI, by navigating to {nav Spaces > Create Space}. By default, only
42
+
administrators can create new Spaces, but you can configure this in the
43
+
{nav Applications} application.
44
+
45
+
The first Space you create will be a special "default" Space, and all existing
46
+
objects will be shifted into this space as soon as you create it. Spaces you
47
+
create later will be normal spaces, and begin with no objects inside them.
48
+
49
+
Create the first space (you may want to name it something like "Default" or
50
+
"Global" or "Public", depending on the nature of your organization), then
51
+
create a second Space. Usually, the second space will be something like
52
+
"Secret Plans" and have a more restrictive "Visible To" policy.
53
+
54
+
55
+
Using Spaces
56
+
============
57
+
58
+
Once you've created at least two spaces, you can begin using them.
59
+
60
+
Application UIs will change for users who can see at least two Spaces, opening
61
+
up new controls which let them work with spaces. They will now be able to
62
+
choose which space to create new objects into, be able to move objects between
63
+
spaces, and be able to search for objects in a specific space or set of spaces.
64
+
65
+
In list and detail views, objects will show which space they're in if they're
66
+
in a non-default space.
67
+
68
+
Users with access to only one space won't see these controls, even if many
69
+
spaces exist. This simplifies the UI for users with limited access.
70
+
71
+
72
+
Space Policies
73
+
==============
74
+
75
+
Briefly, Spaces affect policies like this:
76
+
77
+
- Spaces apply their view policy to all objects inside the space.
78
+
- Space policies are absolute, and stronger than all other policies. A
79
+
user who can not see a Space can **never** see objects inside the space.
80
+
- Normal policies are still checked: spaces can only reduce access.
81
+
82
+
When you create a Space, you choose a view policy for that space by using the
83
+
**Visible To** control. This policy controls both who can see the space, and
84
+
who can see objects inside the space.
85
+
86
+
Spaces apply their view policy to all objects inside the space: if you can't
87
+
see a space, you can never see objects inside it. This policy check is absolute
88
+
and stronger than all other policy rules, including policy exceptions.
89
+
90
+
For example, a user can never see a task in a space they can't see, even if
91
+
they are an admin and the author and owner of the task, and subscribed to the
92
+
task and the view and edit policies are set to "All Users", and they created
93
+
the Space originally and the moon is full and they are pure of heart and
94
+
possessed of the noblest purpose. Spaces are impenetrable.
95
+
96
+
Even if a user satisfies the view policy for a space, they must still pass the
97
+
view policy on the object: the space check is a new check in addition to any
98
+
check on the object, and can only limit access.
99
+
100
+
The edit poilcy for a space only affects the Space itself, and is not applied
101
+
to objects inside the space.
102
+
103
+
11
104
Archiving Spaces
12
105
================
13
106
···
25
118
space.
26
119
27
120
You can reactivate a space later by choosing {nav Activate Space}.
121
+
122
+
123
+
Application Email
124
+
=================
125
+
126
+
After activating Spaces, you can choose a Space when configuring inbound email
127
+
addresses in {nav Applications}.
128
+
129
+
Spaces affect policies for application email just like they do for other
130
+
objects: to see or use the address, you must be able to see the space which
131
+
contains it.
132
+
133
+
Objects created from inbound email will be created in the Space the email is
134
+
associated with.
135
+
136
+
137
+
Limitations and Caveats
138
+
=======================
139
+
140
+
Some information is shared between spaces, so they do not completely isolate
141
+
users from other activity on the install. This section discusses limitations
142
+
of the isolation model. Most of these limitations are intrinsic to the policy
143
+
model Phabricator uses.
144
+
145
+
**Shared IDs**: Spaces do not have unique object IDs: there is only one `T1`,
146
+
not a separate one in each space. It can be moved between spaces, but `T1`
147
+
always refers to the same object. In most cases, this makes working with
148
+
spaces simpler and easier.
149
+
150
+
However, because IDs are shared, users in any space can look at object IDs to
151
+
determine how many objects exist in other spaces, even if they can't see those
152
+
objects. If a user creates a new task and sees that it is `T5000`, they can
153
+
know that there are 4,999 other tasks they don't have permission to see.
154
+
155
+
**Globally Unique Values**: Some values (like usernames, email addresses,
156
+
project hashtags, repository callsigns, and application emails) must be
157
+
globally unique.
158
+
159
+
As with normal policies, users may be able to determine that a `#yolo` project
160
+
exists, even if they can't see it: they can try to create a project using the
161
+
`#yolo` hashtag, and will receive an error if it is a duplicate.
162
+
163
+
**User Accounts**: Spaces do not apply to users, and can not hide the existence
164
+
of user accounts.
165
+
166
+
For example, if you are a contracting company and have Coke and Pepsi as
167
+
clients, the CEO of Coke and the CEO of Pepsi will each be able to see that the
168
+
other has an account on the install, even if all the work you are doing for
169
+
them is separated into "Coke" and "Pepsi" spaces.