Page MenuHomePhabricator

Document a process to request new projects
Closed, ResolvedPublic

Description

On Day 1 we will need a process to request a new project, because plain users will not be able to create projects themselves.

In fact, we need such progress already now in this Labs instance. We can define the process as we document it, and fine tune it as we see fit, real request after real request.

I have started a draft at https://www.mediawiki.org/wiki/Phabricator/Help. @Aklapper & co, feel free fine tuning it while satisfying the current requests for Labs.

Details

Reference
fl457

Event Timeline

flimport raised the priority of this task from to High.Sep 12 2014, 1:42 AM
flimport set Reference to fl457.

MissGayle wrote on 2014-07-15 17:42:18 (UTC)

What're the naming conventions?

project name following the naming conventions (link)

  • Talent & Culture Office

description including the purpose of the project -- you will be able to edit it after the project has been created

  • Tracking HR projects and key deliverables in a transparent manner

access policies -- the defaults are public view and equal access for all registered users

  • public

who can view the project and tasks (list options, default Public)

  • public

who can join the project (list options, default ?)

  • anyone in HR (Gayle, Anna Stillwell, Joady Lohr, Anna Lantz, Emanuela Neagu, Heather McAndrew, Emily Blanchard, Jenn Suzuki, Elena Hernandez)

who can edit tasks (list options)

  • anyone in HR (Gayle, Anna Stillwell, Joady Lohr, Anna Lantz, Emanuela Neagu, Heather McAndrew, Emily Blanchard, Jenn Suzuki, Elena Hernandez)

who can add comments (list options)

  • anyone

(are there more sensible options?)

Rush wrote on 2014-07-15 18:13:13 (UTC)

@MissGayle I'm not sure yet how to respond since the process itself doesn't exist :)

Ok, so a few general thoughts re: project creation I have been hoarding...

  • Naming scheme should depend on the type of project (these determine the icon and picture and maybe color?)
  • work queues (buckets for work to be organized into...overlapping)
  • group of people
  • straight up tag
  • In order to have a naming scheme projects can't be editable by users once created? Otherwise we spend a lot of time ensuring consistent levels of abstraction, and organization and then it's all out the window post-creation process.
  • Project creation isn't a super user priv, just one that requires understanding how this stuff is organized for consistency across the install. I would say, team leads, etc can create? Assuming reasonable good faith in the context for people we trust.
  • This one is sure to be fun :) projects should be not be camel case, also known as lower case only please.

There are a few reasons but the most overt can be demonstrated like this:

this exists: http://fab.wmflabs.org/project/view/40/

Often referenced within the install as http://fab.wmflabs.org/tag/<project>

But, only lower case non-space references work:

http://fab.wmflabs.org/tag/trusted_user_tool/

this type of reference being pretty standard we are going to dig ourselves into a weird space where Security is a project in the project field, yet /tag/Security doesn't reference the object (/tag/security does). That is how it works currently, and it's already confusing and weird.

That means spaces and capitals within a project name force an inconsistency in reference

  • Before creating people centric projects for assigning of rights, etc. An effort should be made to ensure it doesn't exist as another name already. (same logic applied all around I guess)
  • For non-people oriented projects restricting who can join them, not sure if it makes sense?
  • I'm not sure how we limit comment ability unless it's the broader view/edit permissions?
  • The who can join/edit/see type permissions need to be specified in phabricator user account terms

or group terms

Using the request here as a first-through-the-breach instance I have done this:

http://fab.wmflabs.org/T458

Mostly for discussion...

tl;dr to get a new project:

qgil wrote on 2014-07-16 11:54:30 (UTC)

In T457#7, @Rush wrote:
  • Naming scheme should depend on the type of project (these determine the icon and picture and maybe color?)
    • work queues (buckets for work to be organized into...overlapping)
    • group of people
    • straight up tag

Documented at https://www.mediawiki.org/wiki/Phabricator/Help

  • In order to have a naming scheme projects can't be editable by users once created? Otherwise we spend a lot of time ensuring consistent levels of abstraction, and organization and then it's all out the window post-creation process.

Yes, ideally projects can only be renamed by the Phabricator Request Project members.

  • Project creation isn't a super user priv, just one that requires understanding how this stuff is organized for consistency across the install. I would say, team leads, etc can create? Assuming reasonable good faith in the context for people we trust.

I would leave it to Phabricator Request Project memberr, or even something more precise like "Phabricator Project Creators", and then invite there whoever needs to create projects regularly and understands the drill.

  • This one is sure to be fun :) projects should be not be camel case, also known as lower case only please.

??? "Wikimedia Phabricator Day 1" results in http://fab.wmflabs.org/tag/wikimedia_phabricator_day_1/ automatically.

this type of reference being pretty standard we are going to dig ourselves into a weird space where Security is a project in the project field, yet /tag/Security doesn't reference the object (/tag/security does).

How do you get " /tag/Security" apart from typing it manually? Why is this is a problem? I'd rather give preference to a human friendly interface, where projects can be defined with natural names.

About project members, is there a need to define them when requesting a new project? We can create "Project X" with the user requesting its creation as member, and then set permissions so that the "Project X" team can invite new members, right?

qgil wrote on 2014-07-16 12:05:52 (UTC)

In T457#7, @Rush wrote:
  • I'm not sure how we limit comment ability unless it's the broader view/edit permissions?

This might be because I had to recall the types of permission by heart. Can I get momentarily admin access to check those permissions, document accordingly, and then give back (again) the admin rights, please?

Rush wrote on 2014-07-16 15:26:16 (UTC)

@Qgil you are now security!

qgil wrote on 2014-07-16 18:57:07 (UTC)

@Rush I still can't access the admin options to check the possible permissions...

Rush wrote on 2014-07-16 19:01:19 (UTC)

@Qgil, I"m not sure what you are looking at?

your a phab admin (meant in both senses)
your in security group
phabricator-request-project is all users for all fields
http://fab.wmflabs.org/T458 is all users for all fields

what perm screen are you looking for?

qgil wrote on 2014-07-17 11:38:14 (UTC)

I had what I needed, I only couldn't see it.

Anyway, I have simplified the instructions to request a new project. It all boils down to create a task specifying the name and description of the project, and a reasoning for special access permissions if the defaults don't work for you.

There is a note for teams expecting to create several projects. Those will need to start with a project for the team.

https://www.mediawiki.org/wiki/Phabricator/Help#Requesting_a_new_project

I will start testing this process with T458: "ext_ref" field should be hidden/non-editable when submitting a task.

qgil wrote on 2014-07-25 13:55:28 (UTC)

@Rush, see {T495}. It's a project creation request with a strict CamelCase name. You said this is a problem. I asked why and provided my reasons to avoid project names with lower case only and dashes. What is the conclusion?

Rush wrote on 2014-07-25 18:38:35 (UTC)

Sorry, my lack of response to that wasn't meant to be opaque or rude, I've been trying to figure out the best way to make the argument.

I've been here before and the culmination of my thinking boils down to 'oh no not again!', but that's a really difficult thing to communicate. I'm hoping I can at least relate challenges I see here from previous experience.

The case of tags

This exists: http://fab.wmflabs.org/project/view/40/

Only nobody remembers project 40, everyone remembers the name shown at the top as Trusted User Tool, the most common way to reference a project when projects reach a certain scale, especially in Phabricator, is via the /tag/name mechanism. Only that doesn't work out for this name.

This doesn't exist: http://fab.wmflabs.org/tag/Trusted%20User%20Tool/
This doesn't exist: http://fab.wmflabs.org/tag/Trusted_User_Tool/

This does exist: http://fab.wmflabs.org/tag/trusted_user_tool/

Technically per spec the above should work out the spacing UTF8 as %20 and that should be fine, but as anyone who has done url encoding is aware users do not understand URL encoding. Thus the human option of replacing %20 control character with '_'. Which I think is the sanest option, and we should mimic it, to do otherwise is to intentionally create a disparity in how a project is referenced.

If we don't follow the Phabricator standard we now have two names for one thing. This inconsistency means we end up with a page in the wiki that boils down to "how to translate your project name into the tag name". Because it isn't precisely URL spec, even if you ignore the case sensitivity issues.

Versus:

This exists: http://fab.wmflabs.org/project/view/47/
This exists: http://fab.wmflabs.org/tag/operations-core/

On readability and flat namespacing

Taking the case of https://www.mediawiki.org/wiki/Extension:GoogleLogin

Because the project namespace is flat we have to infer hierarchy (sub grouping) with a mostly sane single string naming scheme

Bugzilla:

Mediawiki
  -> Extensions
     -> GoogleLogin

Phabricator:

mediawiki-extensions-googlelogin

Or

Mediawiki-Extensions-GoogleLogin

We are representing the same hierarchy and maintaining namespace isolation consistency with this paradigm. googlelogin is ambiguous while mediawiki-extensions-googlelogin is not.

Taking this camel case idea down the line it becomes things like:

ResearchAndReview-GrantProposals-Ready

versus encouraging lower case and readability:

research-grantmaking

We are labeling things more than we are naming them. Eventually it becomes necessary to follow proper noun usage with things like: GoogleReady-OAuth-LoginProtocol. The limitations of flat namespacing mean we end up with 10, 20, 30 and up character strings for which the CAmELCase usecase is not more readable except in the simplest of cases.

Once we start doing camel case it will be an issue of having to respect all proper nouns which make strings less readable, and going back because we realize it's adding far more problems than it creates readability it will be impossible. The intangible problem of why some Projects are now projects is essentially very difficult culturally. External references all end up inconsistent if we try to change this later.

URL's and Case

So when creating a project name we are really creating a URL reference for a bucket of objects. This isn't the same with other things within the Phabricator landscape. We don't try to hit phab.com/theawesometicket or phab.com/myawesomelegalagreement. We do reference phab.com/tag/project-foo. When you get right down to it case sensitivity and URL's is confusing. Technically, case should be ignored in the FQDN. Google.com and GOOGLE.com are equivalent, but should be respected in the trail. GOOGLE.com/foo and google.com/Foo are distinct. Even that falls apart though because different server implementations can handle those cases in different ways. Even the w3 takes a pragmatic approach. See http://www.w3.org/TR/WD-html40-970708/htmlweb.html and http://www.w3.org/tr/wd-html40-970708/htmlweb.html where rather than respecting the case sensitivity they just redirect, which is pretty much the sane approach for reference documentation like that I guess. But demonstrates the weirdness.

Shown out of love:

yes: http://en.wikipedia.org/wiki/case_sensitivity
yes: http://en.wikipedia.org/wiki/Case_sensitivity
no: http://en.wikipedia.org/wiki/CASE_SENSITIVITY

So projects are going to be directly referenced as URL's and URL's are finicky. There are characters that are OK to use as project names in the absolute sense -- it won't stop you, but are not valid in a URL

I've been doing a lot of testing for how we can move the namespace from bugzilla to phabricator and it has only reinforced these ideas.

Right now in bugzilla we have names that when translated look like: one-two-three/four

This isn't a valid project reference, because it is not a valid URL. That only works as phab.com/tag/one-two-three_four/

If we allow characters in project names that are not valid in a URL we are going to make things much harder for us and users.

Referencing

Projects are also referenced in remarkup as well but this comes with its own inconsistencies. As an example you can refer to user @rush and project #operations-requests. But if we allow non-standard URL characters such as spaces we end up with these cases:

no : Trusted-Contributors User Tool
yes: #Trusted_User_Tool
yes: #trusted_user_tool

Note the same happens for ampersand:

project foo_and_bar is fine: foo_and_bar
project foo&bar is *not* fine: foo_bar

The way this is handled under the covers is this reference is a "hashtag", and since it's infeasible to parse out spaced tags it is converted to the i_am_snake_case whenever a project with a space is created. That means we have two cases within the context of phabricator ignoring the /tag/Trusted User Tool fiasco, it can't be referenced as project in remarkup within any text field as written.

Character Groupings

Probably allowed:

abcdefghijklmnopqrstuvwxyz0123456789-._~:[]!'()*+,;=

Missing due to custom use:

# @

Missing due to inconsistency in reference or incompatbility:

ABCDEFGHIJKLMNOPQRSTUVWXYZ&?/

tl;dr

we are going to regret allowing things to be named in ways that create inconsistent references across the application. please let's not do this and condemn ourselves to explaining it every day for the next ten years

mediawiki-extensions-googlelogin ftw

Florian wrote on 2014-07-28 12:02:33 (UTC)

@Rush: So you would suggest to use always lowercase project namens? But the extension/project itself can still be named "as it is" with CamelCase and/or whitespaces?

qgil wrote on 2014-07-28 14:50:42 (UTC)

@Rush, thank you for the long explanation but I have to say that I still disagree.

Your argument is based on the assumption that people memorize and type entire URLs. This is why having "sane" URLs is key for you, and the rest needs to be adapted to this assumption, sacrificing the use of natural language in the UI.

I believe for most users the UI goes first, and using natural language there makes them happier. Phabricator, web links, search engines, and users' browsers will deal with the full URLs. This is what happens nowadays in most web services, including Wikipedia and our developer infrastructure sites.

Summarizing my opinion:

  • Using original project names in Phabricator makes them easier to type and find.
  • Project names are used as simple tags, except in the case of explicit subprojects of an existing project à la "Product - Component". No "MediaWiki-Extensions-Etc".
  • Since projects are proper nouns, by default they use the regular Title Case. Other uses of case are allowed only when the original project name uses them (e.g. GoogleLogin, VisualEditor, MySQL, FOSDEM)

mediawiki-extensions-googlelogin ftw

Two reasons why this is not a good solution:

  1. If you search for "googlelogin" or any substring, you will not find this project in the search engine or via typeahead in a new task. If the project has separate words like "MediaWiki Extensions GoogleLogin" then yes, starting to type "Goo..." the project will appear and the user can just select it. Test this by typing "Dashes" or "dashes". "test-project-dashes" will never show up, while "Test Project Dashes Searchable" will as soon as you type "D" or "d". If all what users know is the project name, they will find it only with separate words.
  2. Considering the importance of typeahead in Phabricator, we want to avoid having hundreds of entries starting with "mediawiki..." or "wikimedia...". Users with a problem in "GoogleLogin" will come and start typing that string directly. This is not Git/Gerrit or Bugzilla, we don't need to reflect any tree structure. Phabricator is about tags. What is important about "GoogleLogin" is that users can find it or reference it easily. Therefore the best is to use the name as is.

aklapper wrote on 2014-07-28 19:32:47 (UTC)

Heja, let's please move the naming scheme discussion to T68 where we have more target audience (PMs). I will comment on concerns and thoughts brought up here in T68.

qgil wrote on 2014-08-04 16:42:20 (UTC)

I'm resolving this task because we have a process in place:

https://www.mediawiki.org/wiki/Phabricator/Help#Requesting_a_new_project

We will mature the process as we define T68, and with the experience acquired.

importing issue status

flimport closed this task as Resolved.Sep 12 2014, 1:42 AM
flimport added a subscriber: chasemp.
Dzahn removed a subscriber: Dzahn.Oct 3 2014, 12:40 AM