This task describes a training scenario.

Background

T11399 describes a request to add support for locations (like meeting rooms) to Phabricator, primarily for integration with the Calendar application. Some examples of use cases are:

• When a user creates a new event, allow them to select a location from a list of meeting rooms (and prevent double-booking of physical rooms).
• Allow users to figure out how to get to particular meeting rooms on large campuses.
• Provide a way to figure out where someone's desk is so you can go give them a nice compliment in person.

Calendar is a relatively new application (see T7924) and real upstream support for locations is probably a long way away, but this is a fairly good task for becoming familiar with working in the Phabricator codebase since it covers something concrete and isn't too tightly integrated with the rest of the codebase.

Getting Started

The rLOCATIONS repository has skeleton code for building a new locations application that could provide these location/map services (we won't actually try to bring any of this upstream, so don't worry about how the upstream works today). We'll start here and work to add some features.

To get started, clone the rLOCATIONS repository so it is next to phabricator/, like this:

somewhere/ $ git clone ssh://secure@secure.phabricator.com/source/locations.git
somewhere/ $ ls
arcanist/
libphutil/
locations/
phabricator/

Next, edit phabricator/conf/local/local.json and add this key so we load the library.

"load-libraries": [
  "locations/src/"
]

Next, run bin/storage upgrade to initialize database storage for this application:

phabricator/ $ ./bin/storage upgrade

You should see it apply some "locations" patches.

Finally, visit http://your.install.com/locations/ in your browser. If things are configured correctly, you should see a list of locations (currently empty).

The locations/ repository has a bare-bones application that defines one type of object (a "Location"). At first, we'll focus on code in locations/src/applications/locations/, which is the core application code. Some of this code has been slightly simplified relative to real application code, but it's mostly representative of what you'd encounter in the main codebase.

Once you get this far, you're ready to get started building out application features.

Scenario Tasks

Once things are working, you can implement features in any order, although the first couple are probably easier:

• T12005: Locations Scenario: Fix a Typo
• T12008: Locations Scenario: Improve New User Experience (NUX)
• T12009: Locations Scenario: View Controller
• T12007: Locations Scenario: Destroying Locations
• T12006: Locations Scenario: Add API Support

If we get through all that, I'll create more runway by turning these into tasks:

• Implement more support interfaces (subscribers, projects, etc).
• Improve the name transaction (validation, timeline rendering).
• Add a "type" field (meeting room, desk, etc).
• Add "latitude" and "longitude" fields so you can specify the coordinates of a location.
• Use browser location features to query the viewer's current location, and show how far away they are from the Location's coordinates.
• When a user reaches a location, add them to a list of visitors to the location.
• Let users catch pokemon.