From 8953bf92ee85067a96aaa547a986fd7da145dc8d Mon Sep 17 00:00:00 2001
From: Rafa de la Torre <rtorre@cartodb.com>
Date: Fri, 12 Aug 2016 18:56:03 +0200
Subject: [PATCH] Update release process

---
 RELEASE.md | 107 +++++++++++++++--------------------------------------
 1 file changed, 29 insertions(+), 78 deletions(-)

diff --git a/RELEASE.md b/RELEASE.md
index 0db48a2..005557a 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -1,93 +1,44 @@
 # Release & Deployment Process
 
-Please read the Working Process/Quickstart Guide in README.md
-and the Development guidelines in CONTRIBUTING.md.
-
 The release process of a new version of the extension
 shall be performed by the designated *Release Manager*.
 
-Note that we expect to gradually automate more of this process.
-
-Having checked PR to be released it shall be
-merged back into the `master` branch to prepare the new release.
-
-The version number in `pg/cranckshaft.control` must first be updated.
-To do so [Semantic Versioning 2.0](http://semver.org/) is in order.
-
-Thew `NEWS.md` will be updated.
-
-We now will explain the process for the case of backwards-compatible
-releases (updating the minor or patch version numbers).
-
-TODO: document the complex case of major releases.
-
-The next command must be executed to produce the main installation
-script for the new release, `release/cranckshaft--X.Y.Z.sql` and
-also to copy the python package to `release/python/X.Y.Z/crankshaft`.
-
-```
+## 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
 
-Then, the release manager shall produce upgrade and downgrade scripts
-to migrate to/from the previous release. In the case of minor/patch
-releases this simply consist in extracting the functions that have changed
-and placing them in the proper `release/cranckshaft--X.Y.Z--A.B.C.sql`
-file.
+
+## 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
 ```
 
-This will copy the current 'X.Y.Z' released version of the extension to
-PostgreSQL. The corresponding Python extension will be installed in a
-virtual environment in `envs/X.Y.Z`.
-
-It can be activated with:
-
-```
-source envs/X.Y.Z/bin/activate
-```
-
-But note that this is needed only for using the package directly;
-the 'X.Y.Z' version of the extension will automatically use the
-python package from this virtual environment.
-
-The `sudo make deploy` operation can be also used for installing
-the new version after it has been released.
-
-To install a specific version 'X.Y.Z' different from the current one
-(which must be present in `releases/`) you can:
-
-```
+To install a specific version 'X.Y.Z' different from the default one:
+```shell
 sudo make deploy RELEASE_VERSION=X.Y.Z
 ```
-
-TODO: testing procedure for the new release.
-
-TODO: procedure for staging deployment.
-
-TODO: procedure for merging to master, tagging and deploying
-in production.
-
-## Relevant release & deployment tasks available in the Makefile
-
-```
-* `make help` show a short description of the available targets
-
-* `make release` will generate a new release (version number defined in
-  `src/pg/crankshaft.control`) into `release/`.
-  Intended for use by the release manager.
-
-* `sudo make deploy` will install the current release X.Y.Z from the
-  `release/` files into PostgreSQL and a Python virtual environment
-  `envs/X.Y.Z`.
-  Intended for use by the release manager and deployment jobs.
-
-* `sudo make deploy RELEASE_VERSION=X.Y.Z` will install specified version
-  previously generated in `release/`
-  into PostgreSQL and a Python virtual environment `envs/X.Y.Z`.
-  Intended for use by the release manager and deployment jobs.
-```