Update documentation

README.md

@@ -8,19 +8,32 @@ CartoDB Spatial Analysis extension for PostgreSQL.
 * *src* source code
 * - *src/pg* contains the PostgreSQL extension source code
 * - *src/py* Python module source code
-* *release* reselesed versions
+* *release* reseleased versions
 
 ## Requirements
 
 * pip, virtualenv, PostgreSQL
-* python-scipy system package
+* python-scipy system package (see src/py/README.md)
 
 # Working Process
 
 ## Development
 
 Work in `src/pg/sql`, `src/py/crankshaft`;
-use topic branch.
+use a topic branch. See src/py/README.md
+for the procedure to work with the Python local environment.
+
+Take into account:
+
+*  Always remember to add tests for any new functionality
+   documentation.
+*  Add or modify the corresponding documentation files in the `doc` folder.
+   Since we expect to have highly technical functions here, an extense
+   background explanation would be of great help to users of this extension.
+*  Convention: Use snake case (i.e. `snake_case` and not `CamelCase`) for all
+   functions. Prefix functions intended for public use with `cdb_`
+   and private functions (to be used only internally inside
+   the extension)  with `_cdb_`.
 
 Update local installation with `sudo make install`
 (this will update the 'dev' version of the extension in 'src/pg/')
@@ -42,50 +55,48 @@ should be dropped manually before the update.
 If the extension has not previously been installed in a database
 we can:
 
-Add tests...
-
 * `CREATE EXTENSION crankshaft WITH VERSION 'dev';`
 
-Test
+Once the tests are succeeding a new Pull-Request can be created.
+CI-tests must be checked to be successfull.
+
+Before merging a topic branch peer code reviewing of the code is a must.
 
-Commit, push, create PR, wait for CI tests, CR, ...
 
 ## Release
 
-To release current development version
-(working directory should be clean in dev branch)
+The release process of a new version of the extension
+shall by performed by the designated *Release Manager*.
 
-(process to be gradually automated)
+Note that we expect to gradually automate this process.
 
-For backwards compatible changes (no return value, num of arguments, etc. changes...)
-new version number increasing either patch level (no new functionality)
-or minor level (new functionality) => 'X.Y.Z'.
-Update version in src/pg/crankshaft.control
-Copy release/crankshaft--current.sql to release/crankshaft--X.Y.Z.sql
-Prepare incremental downgrade, upgrade scripts....
+Having checkout the topic branch of the PR to be released:
 
-Python: ...
+The version number in `pg/cranckshaft.control` must first be updated.
+To do so [Semantic Versioning 2.0](http://semver.org/) is in order.
 
-Install the new release
+We now will explain the process for the case of backwards-compatible
+releases (updating the minor or patch version numbers).
 
-`make install-release`
+TODO: document the complex case of major releases.
 
-Test the new release
+The next command must be executed to produce the main installation
+script for the new release, `release/cranckshaft--X.Y.Z.sql`.
 
-`make test-release`
+```
+make release
+```
 
-Push the release
+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.
 
-Wait for CI tests
+TODO: configure the local enviroment to be used by the release;
+currently should be directory `src/py/X.Y.Z`, but this must be fixed;
+a possibility to explore is to use the `cdb_conf` table.
 
-Merge into master
+TODO: testing procedure for the new release
 
-Deploy: install extension and python to production hosts,
-update extension in databases (limited to team users, data observatory, ...)
-
-Release manager role: ...
-
-.sql release scripts
-commit
-tests: staging....
-merge, tag, deploy...
+TODO: push, merge, tag, deploy procedures.