Continuous release

Our system is designed to continuously deploy updates as needed with zero downtime.

Our release process is:

Every changes are automatically and continuously deployed in a staging environment
QA testing, retakes and fixes are done on staging environment
When ready, we are deploying batch of changes into the production environment
We communicate on product updates and publish and API changelog

We understand the need of service stability and sustainability and are engaged to deploy updates during the less disturbing period.

We also are engaged to communicate as soon as possible when there will be some breaking changes in our API data model or behavior.

API versioning

The Dotfile API has a major-release versioning strategy (means we use v1, v2, v3, … only). To-date, we only release version 1 (v1) of our API and all changes are bundled in this version. We introduce incremental changes and log them in our API changelog.
As we make changes on our API, it could be breaking or non-breaking changes and it could affect or not your integration. Here is how we think about breaking and non-breaking changes for the Dotfile API.

Breaking changes

We consider a breaking change as one that is not backwards compatible with the previous state of the API, and cause existing integrations to fail or behave unexpectedly. It means if your existing integration was working on the previous version and need to be updated or modified in order to continue on the new version, we introduce a breaking change.

We rarely release breaking changes and always go in favor of a backwards compatibility strategy but if we have no choice here is our process to introduce breaking change in our API:

We identify exactly what will change and communicate to all customers at least one month before we release the breaking change
We deploy backward compatible changes and deprecation notice first and help the migration if necessary
We send multiple reminders of the coming breaking change release (1 month ago, 1 week ago, the day before)
We release the breaking change with the according changelog

Guidelines

The following modifications are considered backwards incompatible:

Removing an existing API endpoint.
Removing, renaming, or changing the type existing properties of
an existing API endpoint.
Removing or renaming possible values of an existing enum type.
Removing existing webhook events.
Changing the authentication method or security protocols used by the API.
Decreasing a rate limit.
Making an existing optional property required on a request body schema
Making validation constraint more strict (for instance decreasing a maximum value or maximum length for a request body string property)

Non-Breaking changes

We considers a non-breaking change as one that is backwards compatible with the previous state of the API. Generally, additive changes are mostly backwards-compatible and we consider them as non-breaking changes. However, we acknowledge that they can still lead to behavioral changes that potentially may be unwanted or unknown for our customers. For example, if you generate a validation schema from our Open API specification and are strict on the changes you could experience errors even if we consider as non-breaking changes.

Guidelines

The following modifications are considered backwards compatible:

Adding a new API endpoint
Making an existing optional property required on a response schema
Adding a new optional property on a request body schema
Adding a new optional query parameters on a request
Adding a new value in an existing enum type.
Making validation constraint less strict (for instance increasing a maximum value or maximum length for a request body string property)
Updating the documentation, description of endpoints or properties
Adding deprecation notice on existing endpoint or properties (this will prepare and announce for a future breaking change)