crankshaft/RELEASE.md

# Release & Deployment Process

The release process of a new version of the extension
shall be performed by the designated *Release Manager*.

## Release steps
1. Make sure `develop` branch passes all the tests.
1. Merge `develop` into `master`
1. Update the version number in `src/pg/crankshaft.control`.
1. Generate the next release files with this command:

  ```shell
  make release
  ```
1. Generate an upgrade path from the previous to the next release by copying the generated release file. E.g:

  ```shell
  cp release/cranckshaft--X.Y.Z.sql release/cranckshaft--A.B.C--X.Y.Z.sql
  ```
  NOTE: you can rely on this thanks to the compatibility checks. 
  
  TODO: automate this step [#94](https://github.com/CartoDB/crankshaft/issues/94)
1. Commit and push the generated files.
1. Tag the release:

  ```
  git tag -a X.Y.Z -m "Release X.Y.Z"
  git push origin X.Y.Z
  ```
1. Deploy and test in staging
1. Deploy and test in production
1. Merge back into develop


## Some remarks
* Version numbers shall follow [Semantic Versioning 2.0](http://semver.org/).
* CI tests will take care of **forward compatibility** of the extension at postgres level.
* **Major version changes** (breaking forward compatibility) are a major event and are out of the scope of this doc. They **shall be avoided as much as we can**.
* We will go forward, never backwards. **Generating upgrade paths automatically is easy** and we'll rely on the CI checks for that.

## Deploy commands

The new release can be deployed for staging/smoke tests with this command:

  ```shell
  sudo make deploy
  ```

To install a specific version 'X.Y.Z' different from the default one:

  ```shell
  sudo make deploy RELEASE_VERSION=X.Y.Z
  ```