User:AKlapper (WMF)/T139210



In order to keep Phabricator projects consistent, new primary projects (components, teams, tags, access groups, spaces) need to follow a simple request process. Secondary projects (sprint, release, goal, milestone, sub-project) can be created directly by users with the appropriate permissions.

New projects
When creating a Wikimedia Phabricator project:
 * Check if you need a project.
 * Decide which type of project you request.
 * Figure out if you need a Project, Sub-Project, Milestone, or Project Column.
 * If you don't know what these are, you need a Project.
 * See Project types for comparisons.
 * Come up with a good 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). Remember that Phabricator is a public place and that the entire community shares Phabricator's flat "Projects" namespace.
 * Sentence case or CamelCase by default.
 * Good: #Phabricator, #MediaViewer, #MediaWiki-Special-pages, …
 * Bad: #Wikimedia Phabricator, #MediaViewer-for-MediaWiki, #Code Review for Phabricator, …
 * Do you need (optional) additional hashtags (#example-project)? They can be in addition to the project name to link to projects in descriptions and comments, as well as to call them in searches typing ahead.
 * Good: #affcom for #Affiliations-Committee.
 * Bad: acronyms nobody will guess, misleading tags, …
 * Projects of Wikimedia chapters and language communities should follow the naming scheme: Chapter-Project (like WMSE-Communication); Language-WikimediaSite (like French-Wiktionary); Language-Sites (like Oriya-Sites). Set the language code as additional hashtag (e.g. xy.wikisource).
 * Remember that Subproject names will be presented in many contexts, without their parent project visible, so do not choose a name that only makes sense in context.
 * Good (?): #MediaViewer → #MediaViewer-Bugs
 * Bad: #MediaViewer →#Bugs
 * For time-limited projects, add dates or quarters after the project name. Do not only use ambiguous terms such as "Q3".
 * Good: #Phragile-Apr-Jun-2016
 * Bad: #Oct-Sprint-Phragile, #Phragile-Q2
 * Come up with a good project description:
 * As Phabricator is a public place, describe the project in a way that allows anybody, also outside of the community, to clearly understand what the project is about.
 * Add links to the relevant project pages so anybody can find more information.
 * Subprojects should link to their Phabricator parent project.
 * Should your project not be fully public and open for everybody? If you think there are good reasons, read below. There are also entirely private Spaces which require filing a task to request their creation.
 * If you are a member of acl*Project-Admins:
 * Is the project of the type "ACL" (e.g. for a Space)? If so, file a task to propose and discuss the project before you create the project.
 * Is the project of the type "sprint" or "release"? Go ahead and create the project.
 * Is the project of any other type? Create the project and document its creation by adding a comment to T103700.
 * If you are not a member of acl*Project-Admins
 * File a task which includes Name, Description, and Type of project (tagging it with Project-Admins if you are creating it yourself). If you think your project should not be fully public and open for everybody, provide good reasons. A member of acl*Project-Admins will create your project, document its creation by adding a comment to T103700, and close the task as resolved. (There is no formal decision process; common sense prevails.)
 * If you have to create projects regularly or more often, consider asking for membership in acl*Project-Admins by providing your reasons in T706.

In case of problems with created projects:
 * If a project has been created with a minor problem (wrong color, wrong icon, description can be improved), anybody is encouraged to fix it or to contact the project creator directly asking them to fix it.
 * If a project created has more complex problems (scope potentially overlapping with other projects, unclear need, etc.), the problem should be reported in a new task assigned to the project creator.

Proposal format
Its best to propose new projects with the following information:
 * Name: ...
 * Project description: ...
 * Project type: ...
 * Optional hashtags: ...

Example proposals can be found at https://phabricator.wikimedia.org/T127007 and https://phabricator.wikimedia.org/T138218

Project Policies
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. Even in this case, edit policies allowing only a single person are not useful as that single person might leave Wikimedia. Remember: If you put edit settings to "This project only" it does not make sense to use the join policy "All users", in this case they just have to join, and then they can edit the project!
 * 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. 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. Remember: If you just change the join policy, people can still add theirself as a member, if they are able to edit the project!

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.

Regarding file attachments attached to a task in a private Space, the file is protected by the same policy as the task it is attached to only if you use drag and drop to upload on the task. If you instead upload a file directly to the Files application via file/upload and then attach it to the task, you will not have the same protection.

Requesting a Space
To request a space:
 * Create a task tagged with the Project-Admins 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:
 * Use this form to create a subproject of #Policy-Admins, following the guidelines for an ACL project (name: acl*GROUPNAME_policy_admins, replace "GROUPNAME" accordingly). Once the sub-project is created, edit the project details and ensure the subproject is configured as follows:
 * "Joinable By" policy is restricted to Phabricator Administrators.
 * "Editable by" policy is restricted to administrators plus 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. Make sure that 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.

Displaying and using a Space
See Phabricator/Help

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 above 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.


 * 1) Check that the previous hashtag was kept as an "additional hashtag" (it currently does so automatically). Otherwise, the references to your project that people added in comments and descriptions will break.
 * 2) Remember to update the links in your project pages and templates. For instance, extension projects need to update their infobox.
 * 3) Check if updates are needed to wikibugs's configuration file
 * 4) Check Phlogiston to see if the project is reported in Phlogiston; if so, you will need to change one or more Phlogiston configuration files.

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