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 theSemantic Versioning 2.0 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

2.4 KiB Raw Blame History