85 lines
2.5 KiB
Markdown
85 lines
2.5 KiB
Markdown
# 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 just the Python tests:
|
|
|
|
```
|
|
(cd python && make test)
|
|
```
|
|
|
|
Installing the Extension and running just the PostgreSQL tests:
|
|
|
|
```
|
|
(cd pg && sudo make install && PGUSER=postgres make installcheck)
|
|
```
|
|
|
|
Installing and testing everything:
|
|
|
|
```
|
|
sudo make install && PGUSER=postgres make testinstalled
|
|
```
|