Jump to content

Phabricator/Creating and renaming projects

From mediawiki.org

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

Creating new projects

[edit]

When requesting or creating projects, there are four things you need to decide:

Good practices for name and description

[edit]
  • 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. Go straight to the point.
    • Subprojects should link to their Phabricator parent project.

Changing a created project

[edit]

Project policies

[edit]

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: Custom Policy: Members of either Trusted-Contributors, acl*project-admins, acl*phabricator, WMF-NDA. 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

[edit]

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

[edit]

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

[edit]

To request a project whose tasks should not be public and should only be accessible by a defined static group of people:

  1. Create a task tagged with the Phabricator project (as Project-Admins rights are not sufficient)
  2. 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.

Administrator notes

[edit]

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

[edit]

See Phabricator/Help#Displaying and using a Space

Editing projects

[edit]

Editing a project (for example its description), a project workboard (creating or hiding columns, column triggers, etc) requires membership in either

Renaming projects

[edit]

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

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.

Examples:

Interpretation

[edit]

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.

History

[edit]

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

Retrieved from "https://www.mediawiki.org/w/index.php?title=Phabricator/Creating_and_renaming_projects&oldid=6798881"