Development process

Now that we have a web site that people unknown to us are using, we need to be somewhat careful with it.

In particulars, public APIs should be developed with special care to how they change. (You can be careless with private APIs.)

Changes are of two kinds:

• Compatible changes
  • addition of new methods (this includes the addition of a new API version, i.e. v4/foo is a different method from v5/foo)
  • addition of new optional arguments
  • adding information to blobs under keys that weren't there before
• Removal of methods after a deprecation period (at least a couple of months)

There should be no incompatible changes (changes that could break a client) to a method in a particular API version.

Any addition should follow these steps:

1. Develop proposal(s)
2. Obtain consensus - this should include project manager
3. Create documentation wiki page or google doc (if too complex to be included in github issue description)
4. Create github issue or (for simple things) extend an existing one
5. Implement tests
6. Implement features (tests passing on development server(s))
7. Create pull request for review by our usual process
8. Deploy to production server(s)
9. Update public documentation (reachable from Open Tree of Life Web APIs)
10. Announce to opentreeoflife-announce list

These don't have to be heavyweight steps; 'develop proposal' and 'obtain consensus' might be done on a hangout. And the above does not preclude experimentation at any point; you can implement before figuring out what to propose, just don't expect it to pass the consensus gate.

The only incompatible public changes should be removals, i.e. the removal of formerly supported methods. Removals should only follow a deprecation period (after the method's successor has been out for a while). We should never have an incompatible change in the behavior of a method - one that could break a client - other than complete failure due to removal. Note that advancing API versions is a compatible change, since the URLs change (all the methods are new).

Flag days, i.e. a zero-length deprecation period, are to be avoided. They require a more delicate process.

A new API version should be at least as functional as the previous one before being announced. I.e. users shouldn't have to mix API versions (even though they can, during the deprecation period). Public review prior to release is a very good idea (this is mandatory in the case of a flag day).