diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 42385dc..ed694bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,7 @@ # Development process -Please read the Working Process/Quickstart Guide in [README.md](https://github.com/CartoDB/crankshaft/blob/master/README.md) first. - For any modification of crankshaft, such as adding new features, -refactoring or bug-fixing, topic branch must be created out of the `develop` -branch and be used for the development process. +refactoring or bugfixing, a topic branch must be created out of the `develop`. Modifications are done inside `src/pg/sql` and `src/py/crankshaft`. @@ -14,80 +11,47 @@ Take into account: (inside `src/pg/test`, `src/py/crankshaft/test`) as well as to detect any bugs that are being fixed. * 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: snake case(i.e. `snake_case` and not `CamelCase`) - 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 - the extension) with `_cdb_`. +* Naming conventions for function names: + - use `CamelCase` + - prefix "public" functions with `CDB_`. E.g: `CDB_SpatialMarkovTrend` + - prefix "private" functions with an underscore. E.g: `_CDB_MyObscureInternalImplementationDetail` Once the code is ready to be tested, update the local development installation with `sudo make install`. This will update the 'dev' version of the extension in `src/pg/` and make it available to PostgreSQL. -It will also install the python package (crankshaft) in a virtual -environment `env/dev`. - -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 -environment with: - -``` -source envs/dev/bin/activate -``` - Update extension in a working database with: -* `ALTER EXTENSION crankshaft UPDATE TO 'current';` - `ALTER EXTENSION crankshaft UPDATE TO 'dev';` - -Note: we keep the current development version install as 'dev' always; -we update through the 'current' alias to allow changing the extension -contents but not the version identifier. This will fail if the -changes involve incompatible function changes such as a different -return type; in that case the offending function (or the whole extension) -should be dropped manually before the update. +```sql +ALTER EXTENSION crankshaft UPDATE TO 'current'; +ALTER EXTENSION crankshaft UPDATE TO 'dev'; +``` If the extension has not previously been installed in a database, it can be installed directly with: - -* `CREATE EXTENSION IF NOT EXISTS plpythonu;` - `CREATE EXTENSION IF NOT EXISTS postgis;` - `CREATE EXTENSION crankshaft WITH VERSION 'dev';` - -Note: the development extension uses the development python virtual -environment automatically. - -Before proceeding to the release process peer code reviewing of the code is -a must. +```sql +CREATE EXTENSION IF NOT EXISTS plpythonu; +CREATE EXTENSION IF NOT EXISTS postgis; +CREATE EXTENSION crankshaft WITH VERSION 'dev'; +``` Once the feature or bugfix is completed and all the tests are passing -a Pull-Request shall be created on the topic branch, reviewed by a peer -and then merged back into the `develop` branch when all CI tests pass. +a pull request shall be created, reviewed by a peer +and then merged back into the `develop` branch once all the CI tests pass. -When the changes in the `develop` branch are to be released in a new -version of the extension, a PR must be created on the `develop` branch. -The release manage will take hold of the PR at this moment to proceed -to the release process for a new revision of the extension. +## Relevant development targets in the Makefile -## Relevant development tasks available in the Makefile +```shell +# Show a short description of the available targets +make help -``` -* `make help` show a short description of the available targets +# Generate the extension scripts and install the python package. +sudo make install -* `sudo make install` will generate the extension scripts for the development - version ('dev'/'current') and install the python package into the - development virtual environment `envs/dev`. - Intended for use by developers. - -* `make test` will run the tests for the installed development extension. - Intended for use by developers. +# Run the tests against the installed extension. +make test ``` diff --git a/README.md b/README.md index 683fb38..9dad032 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ git fetch && git checkout -b my-cool-feature origin/develop ``` 1. Code, commit, push, repeat. 1. Write some **tests** for your feature or bugfix. +1. Update the [NEWS.md](https://github.com/CartoDB/crankshaft/blob/develop/NEWS.md) doc. 1. Create a pull request and mention relevant people for a **peer review**. 1. Address the comments and improvements you get from the peer review. 1. Mention `@CartoDB/dataservices` in the PR to get it merged into `develop`.