Differential D13547 Diff 32733 src/docs/user/userguide/spaces.diviner

Changeset View

Standalone View

src/docs/user/userguide/spaces.diviner

	@title Spaces User Guide			@title Spaces User Guide
	@group userguide			@group userguide

	Guide to the Spaces application.			Guide to the Spaces application.

	Overview			Overview
	========			========

	IMPORTANT: Spaces is a prototype application.

	The Spaces application makes it easier to manage large groups of objects which			The Spaces application makes it easier to manage large groups of objects which
	share the same access policy. For example:			share the same access policy. For example:

	- An organization might make a Space for a project in order to satisfy a			- An organization might make a space for a project in order to satisfy a
	contractual obligation to limit access, even internally.			contractual obligation to limit access, even internally.
	- An open source organization might make a Space for work related to			- An open source organization might make a space for work related to
	internal governance, to separate private and public discussions.			internal governance, to separate private and public discussions.
	- A contracting company might make Spaces for clients, to separate them from			- A contracting company might make spaces for clients, to separate them from
	one another.			one another.
	- A company might create a Space for consultants, to give them limited			- A company might create a spaces for consultants, to give them limited
	access to only the resources they need to do their work.			access to only the resources they need to do their work.
	- An ambitious manager might create a Space to hide her team's work from her			- An ambitious manager might create a space to hide her team's work from her
	enemies at the company, that she might use the element of surprise to later			enemies at the company, that she might use the element of surprise to later
	expand her domain.			expand her domain.

	Phabricator's access control policies are generally powerful enough to handle			Phabricator's access control policies are generally powerful enough to handle
	these use cases on their own, but applying the same policy to a large group			these use cases on their own, but applying the same policy to a large group
	of objects requires a lot of effort and is error-prone.			of objects requires a lot of effort and is error-prone.

	Spaces build on top of policies and make it easier and more reliable to			Spaces build on top of policies and make it easier and more reliable to
	configure, review, and manage groups of objects with similar policies.			configure, review, and manage groups of objects with similar policies.


	Creating Spaces			Creating Spaces
	=================			=================

	Spaces are optional, and are inactive by default. You don't need to configure			Spaces are optional, and are inactive by default. You don't need to configure
	them if you don't plan to use them. You can always set them up later.			them if you don't plan to use them. You can always set them up later.

	To activate Spaces, you need to create at least two spaces. Create spaces from			To activate Spaces, you need to create at least two spaces. Create spaces from
	the web UI, by navigating to {nav Spaces > Create Space}. By default, only			the web UI, by navigating to {nav Spaces > Create Space}. By default, only
	administrators can create new Spaces, but you can configure this in the			administrators can create new spaces, but you can configure this in the
	{nav Applications} application.			{nav Applications} application.

	The first Space you create will be a special "default" Space, and all existing			The first space you create will be a special "default" space, and all existing
	objects will be shifted into this space as soon as you create it. Spaces you			objects will be shifted into this space as soon as you create it. Spaces you
	create later will be normal spaces, and begin with no objects inside them.			create later will be normal spaces, and begin with no objects inside them.

	Create the first space (you may want to name it something like "Default" or			Create the first space (you may want to name it something like "Default" or
	"Global" or "Public", depending on the nature of your organization), then			"Global" or "Public", depending on the nature of your organization), then
	create a second Space. Usually, the second space will be something like			create a second space. Usually, the second space will be something like
	"Secret Plans" and have a more restrictive "Visible To" policy.			"Secret Plans" and have a more restrictive "Visible To" policy.


	Using Spaces			Using Spaces
	============			============

	Once you've created at least two spaces, you can begin using them.			Once you've created at least two spaces, you can begin using them.

	Application UIs will change for users who can see at least two Spaces, opening			Application UIs will change for users who can see at least two spaces, opening
	up new controls which let them work with spaces. They will now be able to			up new controls which let them work with spaces. They will now be able to
	choose which space to create new objects into, be able to move objects between			choose which space to create new objects into, be able to move objects between
	spaces, and be able to search for objects in a specific space or set of spaces.			spaces, and be able to search for objects in a specific space or set of spaces.

	In list and detail views, objects will show which space they're in if they're			In list and detail views, objects will show which space they're in if they're
	in a non-default space.			in a non-default space.

	Users with access to only one space won't see these controls, even if many			Users with access to only one space won't see these controls, even if many
	spaces exist. This simplifies the UI for users with limited access.			spaces exist. This simplifies the UI for users with limited access.


	Space Policies			Space Policies
	==============			==============

	Briefly, Spaces affect policies like this:			Briefly, spacess affect policies like this:
				polybuildrUnsubmitted Not Done Inline Actions Is the extra 's' at the end of 'spacess' intentional? polybuildr: Is the extra 's' at the end of 'spacess' intentional?

	- Spaces apply their view policy to all objects inside the space.			- Spaces apply their view policy to all objects inside the space.
	- Space policies are absolute, and stronger than all other policies. A			- Space policies are absolute, and stronger than all other policies. A
	user who can not see a Space can never see objects inside the space.			user who can not see a space can never see objects inside the space.
	- Normal policies are still checked: spaces can only reduce access.			- Normal policies are still checked: spaces can only reduce access.

	When you create a Space, you choose a view policy for that space by using the			When you create a space, you choose a view policy for that space by using the
	Visible To control. This policy controls both who can see the space, and			Visible To control. This policy controls both who can see the space, and
	who can see objects inside the space.			who can see objects inside the space.

	Spaces apply their view policy to all objects inside the space: if you can't			Spaces apply their view policy to all objects inside the space: if you can't
	see a space, you can never see objects inside it. This policy check is absolute			see a space, you can never see objects inside it. This policy check is absolute
	and stronger than all other policy rules, including policy exceptions.			and stronger than all other policy rules, including policy exceptions.

	For example, a user can never see a task in a space they can't see, even if			For example, a user can never see a task in a space they can't see, even if
	they are an admin and the author and owner of the task, and subscribed to the			they are an admin and the author and owner of the task, and subscribed to the
	task and the view and edit policies are set to "All Users", and they created			task and the view and edit policies are set to "All Users", and they created
	the Space originally and the moon is full and they are pure of heart and			the space originally and the moon is full and they are pure of heart and
	possessed of the noblest purpose. Spaces are impenetrable.			possessed of the noblest purpose. Spaces are impenetrable.

	Even if a user satisfies the view policy for a space, they must still pass the			Even if a user satisfies the view policy for a space, they must still pass the
	view policy on the object: the space check is a new check in addition to any			view policy on the object: the space check is a new check in addition to any
	check on the object, and can only limit access.			check on the object, and can only limit access.

	The edit policy for a space only affects the Space itself, and is not applied			The edit policy for a space only affects the space itself, and is not applied
	to objects inside the space.			to objects inside the space.


	Archiving Spaces			Archiving Spaces
	================			================

	If you no longer need a Space, you can archive it by choosing			If you no longer need a space, you can archive it by choosing
	{nav Archive Space} from the detail view. This hides the space and all the			{nav Archive Space} from the detail view. This hides the space and all the
	objects in it without deleting any data.			objects in it without deleting any data.

	New objects can't be created into archived spaces, and existing objects can't			New objects can't be created into archived spaces, and existing objects can't
	be shifted into archived spaces. The UI won't give you options to choose			be shifted into archived spaces. The UI won't give you options to choose
	these spaces when creating or editing objects.			these spaces when creating or editing objects.

	Additionally, objects (like tasks) in archived spaces won't be shown in most			Additionally, objects (like tasks) in archived spaces won't be shown in most
	search result lists by default. If you need to find objects in an archived			search result lists by default. If you need to find objects in an archived
	space, use the `Spaces` constraint to specifically search for objects in that			space, use the `Spaces` constraint to specifically search for objects in that
	space.			space.

	You can reactivate a space later by choosing {nav Activate Space}.			You can reactivate a space later by choosing {nav Activate Space}.


	Application Email			Application Email
	=================			=================

	After activating Spaces, you can choose a Space when configuring inbound email			After activating spaces, you can choose a space when configuring inbound email
				chadUnsubmitted Not Done Inline Actions This one hurts my head a little. chad: This one hurts my head a little.
	addresses in {nav Applications}.			addresses in {nav Applications}.

	Spaces affect policies for application email just like they do for other			Spaces affect policies for application email just like they do for other
	objects: to see or use the address, you must be able to see the space which			objects: to see or use the address, you must be able to see the space which
	contains it.			contains it.

	Objects created from inbound email will be created in the Space the email is			Objects created from inbound email will be created in the space the email is
	associated with.			associated with.


	Limitations and Caveats			Limitations and Caveats
	=======================			=======================

	Some information is shared between spaces, so they do not completely isolate			Some information is shared between spaces, so they do not completely isolate
	users from other activity on the install. This section discusses limitations			users from other activity on the install. This section discusses limitations
	Show All 28 Lines