crankshaft/CONTRIBUTING.md

# Contributing guide

## How to add new functions

Try to put as little logic in the SQL extension as possible and
just use it as a wrapper to the Python module functionality.

Once a function is defined it should never change its signature in subsequent
versions. To change a function's signature a new function with a different
name must be created.

### Version numbers

The version of both the SQL extension and the Python package shall
follow the[Semantic Versioning 2.0](http://semver.org/) guidelines:

* When backwards incompatibility is introduced the major number is incremented
* When functionally is added (in a backwards-compatible manner) the minor number
  is incremented
* When only fixes are introduced (backwards-compatible) the patch number is
  incremented

### Python Package

...

### SQL Extension

* Generate a **new subfolder version** for `sql` and `test` folders to define
  the new functions and tests
  - Use symlinks to avoid file duplication between versions that don't update them
  - Add new files or modify copies of the old files to add new functions or
    modify existing functions (remember to rename a function if the signature
    changes)
  - 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.
  - Create tests for the new functions/behaviour

* Generate the **upgrade and downgrade files** for the extension

* Update the control file and the Makefile to generate the complete SQL
  file for the new created version. After running `make` a new
  file `crankshaft--X.Y.Z.sql` will be created for the current version.
  Additional files for migrating to/from the previous version A.B.Z should be
  created:
  - `crankshaft--X.Y.Z--A.B.C.sql`
  - `crankshaft--A.B.C--X.Y.Z.sql`
  All these new files must be added to git and pushed.

* Update the public docs! ;-)

## Conventions

# SQL

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_`.

# Python

...

## Testing

Running the Python tests:

```
cd python/crankdown
nosetests test
```

Installing the Python package and running the PostgreSQL tests:

```
sudo pip install python/crankdown --upgrade
cd pg
sudo make install
PGUSER=postgres make installcheck
```