User:AKlapper (WMF)/T139210

These guidelines were discussed in T705 and revised in T97273, T118304, T132888, and T139210.

When and why to request a project

Screencast showing how to request a project

In order to keep Phabricator projects consistent, projects follow a creation process:

Creating new projects

• Need: Check if you need a project.
• Permission: Creating projects requires being a member of Project-Admins. If you would like to create (sub)projects, add a comment in phab:T706 to get permissions. Explaining your plans in a sentence is very welcome.
• Project type:

  

  Types of Projects in Wikimedia Phabricator

  • 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)
  • Private: If you want a project with restricted access (ACL project/Space) whose tasks should not be public and only be accessible by a defined static group of people, create a task with Name, Project description, and Project type.
  • Other: For other types of top-level projects (Component, Umbrella, Team, User-*) and subprojects (Sprint, Release, milestone), you can create them right away. Just follow the icon/color convention.
• Name and Description: Follow the best practices. If you do not, someone might have to spend time edit your project.
• 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.
• That's all. Enjoy!

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 after the project name. Do not only use ambiguous terms such as "Q3".
    • Good: #Phragile-Apr-Jun-2016
    • Bad: #Oct-Sprint-Phragile, #Phragile-Q2
• 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.

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.

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 phabricator: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 Members of… > acl*groupname_policy_admins.
  • 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#Displaying and using a Space

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