This no longer needs to wait for T5873, since enough of that has been sorted out in EditEngine and related work that it can move forward.

T10671 is a similar task for Badges. Here, we'll implement calendar.edit and calendar.search.

The calendar.search method could happen today, calendar.edit needs T9275 first.

The user.addstatus and user.removestatus methods should still be nuked.

@epriestley: Are you open to patches that add more information to the calendar.event.search response? It currently does not even include the event time which is a pretty crucial detail to make the results useful.

Sort of. I'd like to have use cases (what are you trying to do?) first, and I'm not certain what the best representation of dates and times is for external consumption.

There are several general kinds of dates and times:

• Absolute events (like "September 30, 01:23:45 UTC"), which are the most common. You can define these by creating normal events.
• All-day events (like "September 30") where the start and end times of the event depend on the viewer's timezone (since it always starts at 12:00 AM and ends at 11:59:59 PM in your local time). You can define these by creating all day events.
• Floating events (like "September 30, 17:00:00", with no timezone). You can not define these events in the Calendar UI and I don't think they're very useful for most calendar events, but .ics files allow you to define them. "All Day" events are sort of a special case of this.
• Durations (like "4 hours after <any other time format>"). You can not define these events in the Calendar UI and I don't think they're particularly useful either, but .ics files allow you to define them.
• Multivalued events (like "8PM Eastern, 7PM Central, 8PM Pacific"). Certain types of events (here, television episode air times) might have different values in different timezones or regions. You can not define these events in the Calendar UI, I don't think they're very useful, and .ics does not support them either. However, Google Calendar (T2334) may support them, or there's some possibility we may want to support them in the future (although I think this is unlikely).

In virtually every other case where we return date information from the API, it's an absolute timestamp and we can just return an epoch. However, we can only fully represent one of these kinds of datetimes (absolute events) with an epoch timestamp. Thus, our format probably needs to be more involved than just an epoch. I'm not sure exactly what the best format to return is, especially if we want to leave room open for multi-valued events.

Having more information about use cases might help clarify the best approach here.

My first inclination is:

• Return a dictionary with several different representations, so callers with varied needs can do a minimal amount of parsing/mangling.
• Or possibly return a list of those dictionaries, where each item is information for a particular timezone (by default: return UTC and the viewer timezone; maybe let users ask for more), to anticipate multivalued events.

Something like:

"timeFlags": {
  "isAllDay": false,
  "isFloating": false
},
"startTime": [
  {
    "timeZone": "UTC",
    "epoch": 123456789,
    "iso8601": "20160923T232221",
    "display": {
      "default": "Fri, Sep 23, 11:22 PM"
    }
  },
  ...
]

That said, the code to unmangle this would not necessarily really be any simpler than the code to just do more date-time handling with a simpler set of inputs if you're already pretty comfortable with date-time mangling. I'm not sure if doing more date-time work on the server side and returning a more complex structure is a net positive or not. I'm inclined to think this probably is a net positive if most of the clients users want to write are display widgets (since your widget can be a lot simpler if it can just dump a preformatted string directly from the call result to the UI), but maybe not a net positive if most of the clients users want to write are more like importers/exporters.

Even with hypothetical future multivalued events, callers may very rarely care about all of the date-times for an event, so maybe returning just one (requested timezone, or viewer timezone, or UTC) is better and eventually adding an attachment to get all variants in all timezones if you really want to export "8 eastern, 7 central, 8 pacific" intact into another system.

@epriestley:

Here are 2 use-cases which are both essentially the same in all the important ways:

Coordinating code review "office hours" meetings.

Example event: https://phabricator.wikimedia.org/E200

These events are 1-hour IRC meetings where Mediawiki core committers agree to be available to review patches from volunteers (or anyone really) in a synchronous way. The intention is to give immediate feedback on patches and ideally merge as many as possible.

I'd like to make tools for adding a patch to the list of "nominated" patches on a given date and then send IRC reminders to the people involved so that they are reminded to show up for the code review session. This is just beginning to take shape and I'm sure I will come up with more ways to utilize calendar api to coordinate these meetings.

SWAT Deployments

This is similar to the code review sessions, but more formalized and organized. SWAT deployments are recurring events (3 times per weekday I think) where we deploy hot-fixes to production mediawiki branches. It's a kind of releeph process where we cherry-pick urgent patches after a basic code review as long as the author is online and ready to help the deployer with testing and potentially revert if things go wrong.

These deployments currently are organized on a wiki page (https://wikitech.wikimedia.org/wiki/Deployments#Near-term) and it's not very user-friendly. The patch authors must manually add their patches by adding wiki-markup to that page in the appropriate time-slot, then the wiki page html is parsed by various tools and consumed in nasty ways.

I'd like to replace this with a calendar event, yet again like the previous use-case, I want to build a relationship between a 1-hour time slot and a list of patches which will be cherry-picked to various branches and potentially reverted if things go south.

What's needed

I think the best way to go is probably to implement a custom transaction type for adding patches to events and recording what happens with each patch, whether it's merged, postponed, reverted or whatever other states we come up with.

This is sort of starting to sound like releeph but I already tried going down that path and there be dragons.