Phabricator/Creating and renaming projects
In order to keep Phabricator projects consistent, projects follow a creation process:
Creating new projects
- Need: Check if you really need a project.
- Request a single project: If you only need a single project, file a task. See below for information to provide.
- Get permission: Only if you regularly (!) need to create (sub)projects, comment in phab:T706 to become a member of Project-Admins. Explaining your plans in a sentence is very welcome.
When requesting or creating projects, there are four things you need to decide:
- Name and Description: Follow the best practices. If you do not, someone might have to spend time editing your project.
- Project type:
- Decide which type of project you need:
- Tag: If you want to create a Tag project, create a task to allow discussion of the proposal. (Example: T127007)
- Project with limited access: If you want a project in which not all tasks are public, see #Restricting_access_via_Space_policies.
- Other: For other types of projects (Component, Umbrella, Group, User-*, Sprint, Release, milestone), Project-Admins members can create them directly, without first filing a task. Always follow the icon/color convention.
- Policies: Do not change the default "Visible To", "Editable By" and "Joinable By" #Project policies. If you think that you need to change these policies then you likely want to discuss creating a private project (Space) instead.
- Source Repo: Provide a link to the location of the code repository (if applicable).
Good practices for name and description
- Project name:
- Ideally one word, otherwise multiple words should be connected with dashes in order to allow linking project names in 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. Do not only use ambiguous terms such as "Q3"; explain which months a quarter covers (cf. T134134).
- Good: #Phragile-Apr-Jun-2016, #Phragile-FY-2016-17-Q2
- Bad: #Oct-Sprint-Phragile, #Phragile-Q2
- Project description:
- 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.
- The first sentence is important and will show up in the "Browse Project" results. Avoid "Project to keep track of..." or "This project tag is meant to collect tasks about..." etc. but come to the point.
- Subprojects should link to their Phabricator parent project.
Challenging a created project
- Fix minor problems (wrong color, wrong icon, description can be improved) yourself if possible. Contact the owner otherwise. If that doesn't work, create a task assigned to the project creator.
- List of recently created projects in Phabricator.
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 almost never is a reason to restrict the visibility of a project page. Settings other than 'Public' may only be configured by Wikimedia Security.
- Editable By: Trusted-Contributors. Similarly to wiki pages, protecting project pages from being edited by established 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 Group 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.
Note that tasks filed as Security issues are not publicly visible. See Reporting security bugs for more information.
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 phabricator:file/upload and then attach it to the task, you will not have the same protection.
How projects with limited access are implemented
A Space is not a project. Hence a Space itself does not offer a workboard. In order to have a Phabricator project with a workboard and other features, and also to limit access to tasks and other objects within the project, three separate entities are created in Phabricator:
- A Phabricator project. The project itself is public.
- A Phabricator Space. Tasks within a public project can be created within the Space as well, in which case they are invisible and inaccessible to everyone not in the Space.
- An "ACL Project". Because managing the access list of a Space directly requires administrator access, the Space is configured to use the access list of an "ACL Project". This is a regular Phabricator project, following a special naming convention for trackability, whose membership is controllable by a non-administrator. It will not be used for tasks.
Requesting a project with limited access
To request a project whose tasks should not be public and should only be accessible by a defined static group of people:
- Create a task tagged with the Phabricator project (as Project-Admins rights are not sufficient)
- Put into the description:
- The desired name of the project (see #Good practices for name and description above)
- The description of the project
- An explanation of why there are repeatedly tasks in your project which should only be accessible by a defined group of people.
- The group lead (responsible for adding and removing people with access)
- A list of all Phabricator usernames should be able to access objects in that project.
The group lead (requester) is co-responsible for keeping the members list updated, which is done in the ACL project.
You can have public tasks in your public project which are in the default public Space S1, and you can have tasks in the very same public project which are in a separate Space so these tasks can only be seen and accessed by the members of the ACL project corresponding to that Space.
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. Also temporarily set yourself as project member here (otherwise Phabricator will not let you create the Space).
- Create the actual Space. Make sure that both "Visible To" and "Editable By" is set to
Members of… > acl*groupname_policy_admins.
- Add the ACL group to phab:transactions/editengine/maniphest.task/edit/3/ so they can use that form to set the Space.
- Remove yourself as a temporary project member again.
- 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.
- Document the space.
Displaying and using a Space
See Phabricator/Help#Displaying and using a Space
Editing a project (for example its description) requires either membership in the Trusted-Contributors (please see the project description for more information), or membership in acl*Project-Admins if you have to regularly create project tags anyway (see sections above).
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.
- 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.
- Remember to update the links in your project pages and templates. For instance, extension projects need to update their infobox.
- Check if updates are needed to wikibugs's configuration file
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
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.