[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Preparation for API versioning and stabilization

We're getting closer to moving out of alpha on Origin.  When we do that, we will start enforcing API schema evolution (rather than allowing breaking changes).  The first step will be to introduce a v1beta2 API endpoint.  That endpoint will not be public, but will represent what we plan on supporting next.  Once we accumulate enough non-breaking changes we will expose that API and it will become *stable* (and follow the same stability rules as v1beta1).  

The v1beta1 API will be prevented from changing in a breaking fashion:

* Only new optional fields may be added
* Existing fields may not be changed
* Existing constants may not be changed
* New constants may only be added to new fields
* New types can be introduced to old APIs
* To change the behavior on a new field, developers must create a conversion function that converts the new, optional value to the old required value and vice versa
* Changes to any of the types.go files will have to have approval from dan or myself on top of normal review in order to go in

We will promote certain APIs to stable in v1beta1 at different times:

* First group
  * builds (includes webhooks)
  * deployments
  * images
  * templates and config
* Second group
  * routes
  * users
  * projects
  * oauth

We'll draft up more guidelines about this, however, it will be required for all reviewers and developers to be responsible for understanding what a breaking change means and how to apply it.  We'll start slow so folks get familiar with it.  Expect this to happen soon.

If you have a large API change planned, please work with Dan or myself.

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]