cartodb4/crankshaft
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Review and fix the documentation

Browse Source
This commit is contained in:
Javier Goizueta 2016-03-16 15:45:13 +01:00
parent dea6e2f1a7
commit 4ffb2c9664
1 changed files with 40 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
README.md
View File

@ -24,33 +24,43 @@ The `master` branch is used to merge and tag releases to be
deployed in production. deployed in production.
In addition to these two permanent branches, temporal *topic* In addition to these two permanent branches, temporal *topic*
branches will be used for all modifications. branches must be used for all modifications.
## Development ## Development
A topic branch should be created out of the `develop` branch For any modification of crankshaft, including adding new features,
a topic branch must be created out of the `develop` branch
and be used for the development process; see src/py/README.md and be used for the development process; see src/py/README.md
for further details about the Pyhton package development.
Modifications are done inside `src/pg/sql` and `src/py/crankshaft`. Modifications are done inside `src/pg/sql` and `src/py/crankshaft`.
Take into account: Take into account:
* Always remember to add tests (`src/pg/test`, `src/py/crankshaft/test`) * Test must be added for any new functionality
for any new functionality. (`src/pg/test`, `src/py/crankshaft/test`) as well as for
detected any bugs corrected.
* Add or modify the corresponding documentation files in the `doc` folder. * Add or modify the corresponding documentation files in the `doc` folder.
Since we expect to have highly technical functions here, an extense Since we expect to have highly technical functions here, an extense
background explanation would be of great help to users of this extension. 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 * Convention: snake case(i.e. `snake_case` and not `CamelCase`)
functions. Prefix functions intended for public use with `cdb_` shall be used for all function names.
Prefix function names intended for public use with `cdb_`
and private functions (to be used only internally inside and private functions (to be used only internally inside
the extension) with `_cdb_`. the extension) with `_cdb_`.
Update the local development installation with `sudo make install`. Once the code is ready to be tested, update the local development installation
This will update the 'dev' version of the extension in 'src/pg/' and with `sudo make install`.
This will update the 'dev' version of the extension in `src/pg/` and
make it available to PostgreSQL. make it available to PostgreSQL.
It will also install the python package (crankshaft) in a virtual It will also install the python package (crankshaft) in a virtual
environment `env/dev`. environment `env/dev`.
Run the tests with `make test` The version number of the Python package, defined in
`src/pg/crankshaft/setup.py` will be overridden when
the package is released and always match the extension version number,
but for development it shall be kept as '0.0.0'.
Run the tests with `make test`.
To use the python extension for custom tests, activate the virtual To use the python extension for custom tests, activate the virtual
environment with: environment with:
@ -71,23 +81,27 @@ changes involve incompatible function changes such as a different
return type; in that case the offending function (or the whole extension) return type; in that case the offending function (or the whole extension)
should be dropped manually before the update. should be dropped manually before the update.
If the extension has not previously been installed in a database If the extension has not previously been installed in a database,
we can: it can be installed directly with:
* `CREATE EXTENSION crankshaft WITH VERSION 'dev';` * `CREATE EXTENSION crankshaft WITH VERSION 'dev';`
Note: the development extension uses the development pyhton virtual Note: the development extension uses the development python virtual
environment automatically. environment automatically.
Once the tests are succeeding a new Pull-Request can be created. Once the tests are succeeding a new Pull-Request can be created
CI-tests must be checked to be successful. to the develop branch. CI-tests must be checked to be successful.
Before proceeding to the release process peer code reviewing of the code is a must. Before proceeding to the release process peer code reviewing of the code is
a must.
When the code is accepted by the peer reviewing (and CI tests succeed)
a request for release will be send to the Release Manager.
## Release ## Release
The release process of a new version of the extension The release process of a new version of the extension
shall by performed by the designated *Release Manager*. shall be performed by the designated *Release Manager*.
Note that we expect to gradually automate more of this process. Note that we expect to gradually automate more of this process.
@ -124,9 +138,9 @@ The new release can be deployed for staging/smoke tests with this command:
sudo make deploy sudo make deploy
``` ```
This will make the 'X.Y.Z' version of the extension to PostgreSQL. This will copy the current 'X.Y.Z' released version of the extension to
The corresponding Python extension will be installed in a PostgreSQL. The corresponding Python extension will be installed in a
virtual environment in `envs/X.Y.Z` virtual environment in `envs/X.Y.Z`.
It can be activated with: It can be activated with:
@ -141,6 +155,13 @@ python package from this virtual environment.
The `sudo make deploy` operation can be also used for installing The `sudo make deploy` operation can be also used for installing
the new version after it has been released. 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:
```
sudo make deploy RELEASE_VERSION=X.Y.Z
```
TODO: testing procedure for the new release. TODO: testing procedure for the new release.
TODO: procedure for staging deployment. TODO: procedure for staging deployment.