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. (You can be careless with private APIs.)

Any compatible public change should follow these steps:

• Develop proposal(s)
• Obtain consensus (that must include whoever is going to announce and support the feature)
• Create private documentation (if too complex to be included in github issue description)
• Create github issue or (for simple things) extend an existing one
• Implement tests
• Implement features on development servers (tests passing)
• Deploy to production
• Update public documentation (reachable from Open Tree of Life Web APIs)
• Announce to opentreeoflife-announce list

These don't have to be heavyweight steps; 'develop proposal' and 'obtain consensus' might be done on a hangout.

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, where there is no deprecation period, are to be avoided.