Page MenuHomePhorge

Re-brand Phorge
Open, Unbreak Now!Public

Description

"Phabricator" and "Phacility" are trademarked names, and the logo is copyrighted. To start an initial fork we need update the source code and remove references which identify the product as Phabricator in order to abide by trademark/copyright laws and expectations. This particularly needs to be done so that changes to the product are clearly reflected as being work done by Phorge community/organization and not Phabricator/Phacility.

EvanP has communicated that he would be willing to accept an upstream patch that makes the branding of the site configurable/convenient. The primary diffs which pull out mentions of "Phabricator" and "Phacility" should be done in a means that it would be accepted upstream.

The overall strategy is:

  1. Coordinate with upstream to create a revision that easily enables rebranding of the project
    • So far EvanP has made some changes (though not yet landed) which remove most uses of "Phacility" as well as his username from the application, and also remove other miscellaneous things like the ubuntu/centos installation scripts (which use "Phacility" and "Phabricator").
  2. Create a new fork of Phabricator to start Phorge from, based on these rebranding upstream changes
  3. First diverging commit to be re-brand as "Phorge"
  4. Re-apply our current landed changes

For #1 the strategy is going to be

  1. Create a handful of static functions to getPlatformName() = Phabricator, getProjectRepo() = phabricator
  2. Make updates to appearances of "Phabricator" in the interface to prefer, in order:
    1. Removing the name if it's not needed in context
    2. Replacing the name with a generic reference (e.g. "the platform")
    3. Replacing the name with getPlatformName()
  3. Make updates to uses of phabricator as a path to use getProjectRepo(), including phutil_get_library_root()
  4. Add a ReMarkup parser that can swap out something like ${{{ platform.name }}} to use getPlatformName()
  5. Update diviner documents to use this new remarkup block to allow easily re-branding the documentation
    • Note however that document titles do not use remarkup for rendering, so a different solution will be needed for where "Phabricator" appears in diviner document names.
  6. Update code which produces links to diviner documents based on the document name to do a similar platform-name swap out
  7. Create new diviner documents based on user-exposed references to Tnnnn or phurl.io, based on the relevant content hosted on secure.phabricator.com
  8. Updated references to Tnnnn or phurl.io links to instead link to the new diviner documents
  9. Leave HTTP headers and Email headers alone for now. I'm not sure there's anything reasonable that can be done for these (it might be possible to update HTTP headers without any regressions though I'm not familiar enough with what they're used for).

Additionally EvanP provided a proof-of-concept which would allow for mass-renaming files to strip out "Phabricator" but still allow classes defined as PhabricatorXYZ to be loaded by PHP. This works through some reflection hackery and would require us to build a mapping of old classname -> new classname. This would allow us to more confidently rename classes, as any used via reflection would still load properly even if using the old class name.


Various places identified as indicating "Phabricator"

  • Various places in the settings
  • Auth app
  • Diviner mentions Phabricator in the command line example for building docs and additionally calls it Phabricator documentation
  • Emails mention Phabricator in various subjects, bodies and sender names
  • Logo, Phorge-branded assets to be created via T15005: Create Logo / Brand Assets
  • ./NOTICE has some legal text we might need help with.
  • Emails have a bunch of X-Phabricator-* headers, for configuring rules in mail clients.
    • We may want to allow installs to keep it as Phabricator for compatibility
  • PhabricatorAphlictManagementWorkflow.php has several hard-coded paths assuming the project is checked out under the directory name of phabricator, which will need changed to checking phorge first and then phabricator if it doesn't exist, otherwise installing Aphlict will fail to locate the default configuration file for anyone starting from a fresh install vs. updating their existing checkout.
  • PhabricatorDaemonsSetupCheck.php creates several setup issues with .addCommand('phabricator/ $ ./bin/phd ...'). I believe this is just text that is displayed to the admins of a site however the phabricator/ here represents the repository of the project. This along with the above issue related to Alphict assuming phabricator as a directory name we may need to extract out a similar "project repo name" to be used in these places.
  • PhabricatorPHPPreflightSetupCheck.php creates a setup issue which includes a link using https://phurl.io -- these Phurl links will direct to content hosted on secure.phabricator.com. I'm not sure what to do about these. In this case the content being linked to is https://secure.phabricator.com/T12101. We probably need to extract the content into a Diviner doc and link to that instead? Looking at some of the other setup issues linking to docs/content it looks like there's a way to do this via PhabricatorEnv::getDoclink('Managing Daemons with phd') which I'm assuming links to https://secure.phabricator.com/book/phabricator/article/managing_daemons/.
  • PhabricatorConfigConsoleController.php the loadVersions() method has hardcoded references to phabricator and arcanist repository names which are used to inspect the version. It also inspects the git repository looking for remotes that are hosted on either github.com or secure.phabricator.com. We will need to update the repository name checking and the remote locations to swap secure.phabricator.com to we.phorge.it.
  • PHUIBadgeExample.php creates an example "Lead Developer" badge with the title of "Lead Developer of Phabricator" which we can change to "Phorge" but has a "source" of "Direct Award (epriestley)". This page is all example usage of UI mostly for Phabricator developers. I'm fine with keeping these types of tributes to epriestley but we should check with Evan if he'd like to have his name removed as well. Checking on https://secure.phabricator.com/uiexample/view/PHUIBadgeExample/ it doesn't look like this actually appears in the UI but this might be a bug -- in the resulting HTML this information does appear and is supposed to show on the "back" of the badge when it's flipped over by clicking it.
  • PhabricatorEnv.php in the initializeCommonEnvironment() and getEmptyCWD() functions there are hardcoded calls to phutil_get_library_root('phabricator'). When we extract the repository name we will need to search for other uses of phutil_get_library_root() as there are likely other phabricator we need to extract.
  • PhabricatorEnv.php in the getDocLink() function it hardcodes the project URI to https://secure.phabricator.com.
  • scripts/sql/manage_storage.php script sets a multi-line synopsis using <<<EOHELP block which is not translated using pht(). We might just need to address this in a separate diff to hardcode "Phorge" after the other changes. Although in other PHP scripts it looks like this can be sent through pht() (see PhabricatorClusterConfigOptions.php use of <<<EOTEXT)
  • scripts/sql/manage_storage.php will spit out an error during an exception which references phabricator/ $ ./bin/config ..., there are likely numerous of these throughout the scripts/ files.
  • The following SQL migration files print translated text with "Phabricator". These could be changed but are also probably fine to leave as-is.
    • resources/sql/patches/20130820.file-mailkey-populate.php
    • resources/sql/patches/20130611.migrateouath.php
    • resources/sql/patches/20130820.file-mailkey-populate.php
  • PhabricatorCoreConfigOptions.php an example for phabricator.base-uri is given as http://phabricator.example.com/. This should be changed to https://phorge.example.com in a separate diff after everything else is merged. Same with phabricator.production-uri, phabricator.allowed-uris. This also shows up in the didValidateOption() function when an exception is thrown with an error message.
  • PhabricatorMetaMTAConfigOptions.php defines $single_description to be text that includes example email addresses using phabricator@example.com which should be updated after the changes are merged.
  • PhabricatorMySQLConfigOptions.php defines options which default the storage.default-namespace to phabricator as well as mention that value in the description.
  • PhabricatorSetupIssueView.php uses hsprintf() to print out phabricator/ $ ./bin/config ... text, another hard-coded repo reference
  • PhabricatorSetupIssueView.php has a function renderRestartLink() which looks up a Diviner book by title, "Restarting Phabricator" which will need to be updated to match our Diviner book.
  • PhabricatorOAuthServerApplication.php has a function getHelpDocumentationArticles() which retrieves a Diviner doc by title, "Using the Phabricator OAuth Server". This will need to be updated to match our Diviner book title.
  • PhabricatorSpacesNamespaceEditor.php the getEditorApplicationClass() function is returning a translated version of a class name. This looks wrong and the call to pht() should probably be removed?
  • PhabricatorProjectBuiltinsExample.php has a function renderExample() which calls phutil_get_library_root('phabricator') which will need updated to use the project repo name instead.
  • The following bash scripts print out "Phabricator" and will need updated
    • scripts/install/install_ubuntu.sh
    • scripts/install/update_phabricator.sh
  • PhabricatorBaseURISetupCheck.php has a function executeChecks() which uses https://phabricator in example text. This will need to be updated.
  • PhabricatorBaseURISetupCheck.php also uses phabricator/ $ ./bin/config ... example that will need updated to use the project repo.
  • PhabricatorBinariesSetupCheck.php renders a reference to T3046 which is only valid reference on secure.phabricator.com. Probably make a Diviner doc for this information and link to that instead.
  • PhabricatorBinariesSetupCheck.php includes a path reference to phabricator/support/bin/ which will need updated to use the project repo.
  • PhabricatorConfigExtraSetupCheck.php uses csprintf() to give several examples with phabricator/ $ ./bin config ... which will need updated to use the project repo.
  • PhabricatorConfigExtraSetupCheck.php prints several references to tasks using Tnnnn, we will need to build Diviner docs to cover this content and update references to link to those instead.
  • PhabricatorManualActivitySetupCheck.php has several examples with phabricator/ $ ./bin/... which will need updated to use the project repo.
  • PhabricatorManualActivitySetupCheck.php renders several links to phurl.io addresses which redirect to a tasks/content on secure.phabricator.com. We will need to build a Diviner doc with this information update the link.
  • PhabricatorMySQLSetupCheck.php has a use of phutil_get_library_root('phabricator') which will need replaced with the project repo

Event Timeline

cark updated the task description. (Show Details)

I tried to get a start on this in P1, just running

grep -r -n -E '[Pp]habricator[ \.,;:\-\!\?)]' ./src

and found a few occurrences. Not sure how we want to handle the configuration values that are `phabricator.<XYZ>' since they're sort-of internal, sort-of exposed in the UI. I left them in the Paste just to have them documented

git grep phurl.io has a about 10 links to documentation (mostly in Setup checks).

From my notes

  • webroot/rsrc/image/logo/light-eye.png (rename)
  • webroot/rsrc/favicon/favicon-16x16.png
  • webroot/rsrc/favicon/mask-icon.svg
  • webroot/rsrc/css/application/base/main-menu-view.css (references light-eye.png)
  • src/view/page/menu/PhabricatorMainMenuView.php (uses default wordmark of 'Phabricator')
  • src/applications/config/custom/PhabricatorCustomLogoConfigType.php (the config for the wordmark used in the top-left of the web application, defaults placeholder to 'Phabricator')
  • PhabricatorConfigEditor::getEditorObjectDescription() references "Phabricator"

There are a good chunk of hardcoded Phabricator all over the different config names/descriptions - /config/settings/all/. We might not need to migrate/change the config names but the descriptions will need updated to pull the configured project/wordmark.

Hmm actually I am confusing wordmark with project name currently. Any place that currently has "Phabricator" should not pull the wordmark, but instead we need a new configuration for the branded project name. The difference here would be someone wants to fork Phabricator as a new project with a different name, but sites that want to install it may still wish to modify the wordmark to be distinguished.

Matthew changed the visibility from "All Users" to "Public (No Login Required)".Jun 11 2021, 23:52

Is this happening on rP, or on github somewhere?

I don’t think it has really started yet. I had some changes on GitHub which I’ve abandoned but I think those changes were copied into the install here.

./NOTICE has some legal text we might need help with.

  • Emails have a bunch of X-Phabricator-* headers, for configuring rules in mail clients.

I don't know how often they are used (GMail doesn't support rules based on headers), but we may want to allow installs to keep it as Phabricator for compatibility.

Emails have a bunch of X-Phabricator-* headers, for configuring rules in mail clients.

  • We may want to allow installs to keep it as Phabricator for compatibility

Adding both versions at the same time would give a window for people to update their filter scripts.

avivey triaged this task as Unbreak Now! priority.Jun 23 2021, 18:26

I've created a task upstream to start the discussion about how to rebrand
https://secure.phabricator.com/T13658

Note that epriestley has provided valuable insight and even looked at making some updates
https://secure.phabricator.com/T13658
https://secure.phabricator.com/D21678

He's made several great suggestions. To level-set on expectations these rebranding changes are likely going to take a fair amount of effort, which with my own availability and (lack of) PHP developer effectiveness may take a while to get through. I think these are the options we have:

  1. Cooperate with upstream to develop changes they would accept. Once they're accepted/landed upstream _then_ fork the project, land a change with a rebrand, and land all our existing customizations/changes.
  2. Continue forward with the approach in D25002.

I would prefer option 1 as I think option 2 results in a large initial divergence from the upstream in core/essential/foundational parts of the project.

I think despite either option we can also figure out how to better parallelize the work. I think how we manage that will differ based on which option we move forward with however.

What are everyone else's thoughts?

If the up stream is willing to accept any patches related to rebranding I think getting that implemented and then creating the fork would be ideal and then we can start continuing to update the code base here while other people that clone it can just rebrand for their businesses or use cases or whatnot (or additional forks)

This may end up taking more time but I think this makes the most sense in regards to just making the software more open and versatile

In T15006#279, @avivey wrote:
  • Emails have a bunch of X-Phabricator-* headers, for configuring rules in mail clients.

I don't know how often they are used (GMail doesn't support rules based on headers), but we may want to allow installs to keep it as Phabricator for compatibility.

Maybe this is at least sort of public-facing branding to where it should be or have to be changed...

On the topic of this whole thread.... what if we come up with a standard highly-greppable name to get the ball rolling... The idea is that if it needs to change or become configurable, it's easy to find very specifically...

Example: Phorid (Short for "Phorge Identifier")..

"Forid" doesn't seem to have an English definition, though "Florid" (Phlorid) does...

So the headers would become X-Phorid-* .. Seems worth having a config variable for this, so that's one way to use a placeholder such as Phorid.. to use it anywhere that will eventually (or rather quickly) be swapped with a configuration variable (which would then of course be set to Phorge)....

Example here: https://we.phorge.it/source/phorge/browse/master/src/applications/metamta/engine/PhabricatorMailEmailEngine.php$379

$headers[] = $this->newEmailHeader('X-Phabricator-Must-Encrypt', 'Yes');

Becomes:

$headers[] = $this->newEmailHeader('X-Phorid-Must-Encrypt', 'Yes');

For initial migration, then later becomes something like:

$headers[] = $this->newEmailHeader('X-' . PhabricatorEnv::getEnvConfig('core.instance-indentifier') . '-Must-Encrypt', 'Yes');

Another reason I'm suggesting this is because I really want to jump in and check some of these boxes, and it would help warm up cold feet to know that these variables would be easily findable in the code...

There could even be a subdomain alias for this specific purpose: https://phorid.phorge.it/ (though the migration subdomain could be something else greppable like https://to.phorge.it/)

I think in the case of email headers we would want to duplicate the headers to allow sites migrating time to update their dependence on the existing email headers -- so duplicate the headers to include both X-Phabricator-XYZ and X-Phorge-XYZ, then in a year or so remove X-Phabricator-XYZ. I'm not sure if HTTP headers would be used the same way and might be possible to change those without a migration period.

In T15006#839, @speck wrote:

I think in the case of email headers we would want to duplicate the headers to allow sites migrating time to update their dependence on the existing email headers -- so duplicate the headers to include both X-Phabricator-XYZ and X-Phorge-XYZ, then in a year or so remove X-Phabricator-XYZ. I'm not sure if HTTP headers would be used the same way and might be possible to change those without a migration period.

Good plan... so in that case it would be useful to have a deprecation notice before the X-Phabricator-.... lines.

There is this: https://docs.phpdoc.org/guide/references/phpdoc/tags/deprecated.html

Not that the whole thing should use PHPDoc scattered around, but it would be an option for a standard greppable deprecation notice that would also be parse-able by some IDEs..

TBH, I'm a little confused about the way forward here, and I think this our biggest blocker?
I have some time I can put towards this, but I'm not sure what I should be doing.

In T15006#849, @avivey wrote:

TBH, I'm a little confused about the way forward here, and I think this our biggest blocker?
I have some time I can put towards this, but I'm not sure what I should be doing.

What I understand is that public-facing branding has to be updated, and also some directory structures and URLs... The main directory has changed from phabricator to phorge

Email headers may be a special case, where a transition is introduced -- so in that case there are two headers sent, and the one that references Phabricator is deprecated with a plan to remove it after some time...

But something like this: phutil_get_library_root('phabricator')

Would become: phutil_get_library_root('phorge')

I suppose that even though it could be an opportunity to set a stage to make it configurable doesn't mean it has to be or even should be...

Actually here is where that particular library is registered: https://we.phorge.it/source/phorge/browse/master/src/__phutil_library_init__.php$3

So changing that to phutil_register_library('phorge', __FILE__);

Should in theory allow calls to phutil_get_library_root('phorge') to return the right path...

There's a lot of work to be done here. I've been coordinating with upstream to find a solution, though EvanP has indicated that we should probably take a few swings at solutions to see what does or doesn't work out. I've been out for the past week on holiday so I haven't made any recent progress.

This is the path that I'm going to be working on

  1. Coordinate with upstream to create a revision that easily enables rebranding of the project
    • So far EvanP has made some changes (though not yet landed) which remove most uses of "Phacility" as well as his username from the application, and also remove other miscellaneous things like the ubuntu/centos installation scripts (which use "Phacility" and "Phabricator").
  2. Create a new fork of Phabricator to start Phorge from, based on these rebranding upstream changes
  3. First diverging commit to be re-brand as "Phorge"
  4. Re-apply our current landed changes

For #1 the strategy is going to be

  1. Create a handful of static functions to getPlatformName() = Phabricator, getProjectRepo() = phabricator
  2. Make updates to appearances of "Phabricator" in the interface to prefer, in order:
    1. Removing the name if it's not needed in context
    2. Replacing the name with a generic reference (e.g. "the platform")
    3. Replacing the name with getPlatformName()
  3. Make updates to uses of phabricator as a path to use getProjectRepo(), including phutil_get_library_root()
  4. Add a ReMarkup parser that can swap out something like ${{{ platform.name }}} to use getPlatformName()
  5. Update diviner documents to use this new remarkup block to allow easily re-branding the documentation
    • Note however that document titles do not use remarkup for rendering, so a different solution will be needed for where "Phabricator" appears in diviner document names.
  6. Update code which produces links to diviner documents based on the document name to do a similar platform-name swap out
  7. Create new diviner documents based on user-exposed references to Tnnnn or phurl.io, based on the relevant content hosted on secure.phabricator.com
  8. Updated references to Tnnnn or phurl.io links to instead link to the new diviner documents
  9. Leave HTTP headers and Email headers alone for now. I'm not sure there's anything reasonable that can be done for these (it might be possible to update HTTP headers without any regressions though I'm not familiar enough with what they're used for).

Additionally EvanP provided a proof-of-concept which would allow for mass-renaming files to strip out "Phabricator" but still allow classes defined as PhabricatorXYZ to be loaded by PHP. This works through some reflection hackery and would require us to build a mapping of old classname -> new classname. This would allow us to more confidently rename classes, as any used via reflection would still load properly even if using the old class name.

This is what I currently have planned. I'll update the task description with this information.

Also note,

Given the amount of work involved here, I would perhaps maybe suggest you identify and implement, like, 3-5 useful patches which aren't upstreamable before moving forward with this, just to make sure you don't end up sinking a ton of hours into something that's sort of moot. (But maybe there's already a clear case for doing this legwork.)

@speck What can I help with here? - Are we waiting on upstream for anything currently?

I can provide more information later this weekend but I think it would help if we set up a virtual meeting with anyone interested in helping to get this done.

I think I’ve worked with upstream to understand what changes they would likely accept and it’s a matter of getting things organized and segmented into reviewable pieces.

Additionally for testing I haven’t spent any time getting a Phabricator environment working on my main personal development machine which is a windows box. That’s been a personal hurdle in terms of gaining momentum.

In T15006#1429, @speck wrote:

I can provide more information later this weekend but I think it would help if we set up a virtual meeting with anyone interested in helping to get this done.

Yes - I could have some availability - Normally evenings (US Central Time) -

I think I’ve worked with upstream to understand what changes they would likely accept and it’s a matter of getting things organized and segmented into reviewable pieces.

Additionally for testing I haven’t spent any time getting a Phabricator environment working on my main personal development machine which is a windows box. That’s been a personal hurdle in terms of gaining momentum.

If you have docker for windows and vscode, this setup is a cinch - https://github.com/willson556/phorge-devcontainer

Also this Vagrant pattern should work first-run with vagrant up: https://we.phorge.it/T15027#852

In T15006#1429, @speck wrote:

I can provide more information later this weekend but I think it would help if we set up a virtual meeting with anyone interested in helping to get this done.

I'd like to join, but I'm but my availability is wacky due to being in a strange timezone. I'll try to work with what you can find.

In T15006#1429, @speck wrote:

I can provide more information later this weekend but I think it would help if we set up a virtual meeting with anyone interested in helping to get this done.

I'm interested in joining the meeting