Phabricator/Creating and renaming projects

New projects
Any member of the Project-Creators group can create new projects. Members of the Project-Creators group who have created a new project are supposed to document the creation of that new project (except for Sprint and Release projects) by adding a comment to T103700. If you would like to request the creation of a new project, [ create a new task] under Project-Creators including these details:


 * Name
 * Description
 * Type of project
 * Policy (only if different from the default)

See Phabricator/Projects for a list of existing projects.

Phabricator is a public place. In order to keep some sanity and consistency, new tags and private projects must [ be proposed and discussed before being created]. Any other project types (except for sprints and releases) must be documented by adding a comment to T103700. This is true for everybody, project creators included. There is no formal decision process; common sense prevails. After someone has created the project, the person changes the status of the dedicated task to "resolved".

If a project is missing quality requirements or found problematic, a task can be created assigned to the creator of the project, describing what is missing. The project could be archived until its situation is clarified.

Name

 * Think of the shortest name that users can find easily typing ahead.
 * Ideally one word, otherwise multiple words must be connected with dashes in order to allow linking project names in the context of Phabricator's markup (cf. T43).
 * Unnecessary use of frequent words like "Wikimedia" or "MediaWiki" should be avoided, except for differentiation to help avoiding misunderstandings (e.g. WMF-Design for a Wikimedia Foundation team project, in contrast to general design issues)
 * Sentence case or CamelCase by default.

Good: Phabricator, MediaViewer, MediaWiki-Special-pages...

Bad: Wikimedia Phabricator, MediaViewer-for-MediaWiki, Code Review for Phabricator...

Description

 * Describe the project in a way a newcomer would understand it.
 * Add links to the relevant project pages.
 * Subprojects should link to their Phabricator parent project.

Type of project
This section was moved to Phabricator/Project management.

Additional hashtags
Hashtags are used to link to projects in descriptions and comments, as well as to call them in searches typing ahead.


 * Optional field, you can leave it empty.
 * Or you can add shorter / alternative tags that clearly identify with your project.

Good:  for Affiliations-Committee.

Bad: acronyms nobody will guess, misleading tags...

Policy
IMPORTANT: these policies apply to a project (and its page) itself, not to the tasks assigned to a project!

The default access policies for Wikimedia Phabricator projects should be set to:
 * Visible To: Public (no login required). There should be no reason to restrict the visibility of a project page.
 * Editable By: All Users. Similarly to wiki pages, protecting project pages from being edited by All Users should be an exceptional measure to respond to abuse, and to secure ACL projects.
 * Joinable By: All Users. To be used mainly for Team type projects where membership provides special access to features. If you want to restrict this option you need to justify this decision in your request. Note that Phabricator allows to subscribe and watch projects only to their members. If you want users to follow and work in your project, you should let users join your project. If there are repeatedly tasks in your project which should not be public and only be accessible by a defined group of people, consider asking for the creation of a Space (in parallel to your project). If you would like to list members of your team, you can do so editing the project description.

This policy corresponds to the policies of wiki pages of teams, projects, extensions, etc, in mediawiki.org. Just like there is no reason to protect project wiki pages by default, there is no reason to protect Phabricator project pages by default.

Restricting access via Space policies
Spaces (upstream documentation) allow configuring groups of objects (like tasks) with the same view policies. Some group might have certain types of tasks in their projects which they can only make accessible to group members. In this case, a space for that group can be set up.

Spaces apply their "Visible To" policy to all objects (like tasks) inside the space. A Space's policy is absolute and stronger than any other policy rules. If a user cannot see a space, the user can never see objects inside the space either, even if they are author, assignee or subscriber of the task in that space. (To allow users which are not member of the space to view or edit an object in the Space, a Custom Policy needs to be applied on the object instead of a Space.) In addition to a Space's policy, the view policy on the specific object/task is still applied.

By default, objects are in the public Space (S1). Any other Spaces have a more restrictive "Visible To" policy applied to their objects.

Requesting a Space
To request a space:
 * create a task against the Project-Creators project and explain why there are repeatedly tasks in your project which should only be accessible by a defined group of people.
 * Please indicate the name that should be used for the space
 * Please identify the group lead
 * Please also describe which specific Phabricator users should be able to access objects in that space.

Access to a specific Space is defined via an ACL project which an admin will create when also creating the Space: The members of that ACL project have access to tasks which are in that Space. The ACL project itself will not be used for associating tasks with it. The group lead (requester) is co-responsible for keeping the members list of the ACL project updated.

You can have public tasks in your public project which are in the default public Space (not restricted), and you can have tasks in the very same public project which are in a separate Space which can only be accessed by the members of that ACL/private project.

The following bullet points are only relevant for Phabricator administrators who will create a Space:
 * create an ACL project ("acl*groupname_policy_admins"; replace "groupname" accordingly). The "Joinable By" policy is restricted to Phabricator Administrators. The "Editable by" policy is restricted to administrators and the group lead. Project members are set to those user names (group members) who will be able to access tasks in the Space.
 * create the actual Space. Both "Visible To" and "Editable By" is set to.
 * Note: The "Visible To" setting controls both who can see the space and who can see objects inside the space. The "Editable By" policy only affects the space itself, not objects inside the space.
 * add "Allow members of acl*groupname_policy_admins" to Phabricator's global custom "Can Edit Task Policies" setting. This is required to display the "Visible To" and "Editable By" fields (and hence the Spaces dropdown for members of that Space) in the task creation form.

Displaying and using a Space
Please also see the three screenshots.



If you can access at least two spaces, you see an additional Spaces dropdown under "Visible To" when creating and editing an object. Users with access to only one space will not see this control.



In Maniphest's task view, the Space will also be displayed in front of the task summary. You can batch-edit tasks to move them to a different Space.

Note that you will still have to associate the corresponding "public" project (if existing) to a task to make a task in a restricted Space (which you have access to) to show up in search queries and the workboard of the project. The "public" project could be automatically added via requesting a global Herald rule.

Renaming projects
By default, all users can rename a project. The requirements are project consensus (obviously, and the Phabricator maintainers will not check that you got it) and compliance with the guidelines listed below on this page.

Renaming a project is similar to renaming a wiki page. You need to make sure that you are not leaving broken links after the change of name.


 * Check that the previous hashtag was kept as an additional hashtag. Otherwise, the references to your project that people added in comments and descriptions will break.
 * Remember to update the links in your project pages and templates. For instance, extension projects need to update their infobox.

Something to consider if you project has a volatile name: use URLs with the project number in wiki pages and other external resources. This saves you problems when the project is renamed, since the project number stays the same.

https://phabricator.wikimedia.org/project/board/5/ vs https://phabricator.wikimedia.org/tag/phabricator/ https://phabricator.wikimedia.org/project/profile/5/ for the project description page of the Phabricator project