Contributing

Requirements

Before submitting a pull request on GitHub, please make sure you meet the following requirements:

  • The pull request points to main branch.

  • Changes are squashed into a single commit. I like to use git rebase for this.

  • Commit message is in present tense. For example, “Fix bug” is good while “Fixed bug” is not.

  • Sphinx-compatible docstrings.

  • PEP8 compliance.

  • No missing docstrings or commented-out lines.

  • Test coverage remains at %100. If a piece of code is trivial and does not need unit tests, use this to exclude it from coverage.

  • No build failures. Builds automatically trigger on pull request submissions.

  • Documentation is kept up-to-date with the new changes (see below).

Warning

The dev branch is occasionally rebased, and its commit history may be overwritten in the process. Before you begin your feature work, git fetch or pull to ensure that your local branch has not diverged. If you see git conflicts and want to start with a clean slate, run the following commands:

~$ git checkout dev
~$ git fetch origin
~$ git reset --hard origin/dev  # THIS WILL WIPE ALL LOCAL CHANGES

Style

To ensure PEP8 compliance, run flake8:

~$ pip install flake8
~$ git clone https://github.com/arangodb/python-arango.git
~$ cd python-arango
~$ flake8

If there is a good reason to ignore a warning, see here on how to exclude it.

Testing

To test your changes, you can run the integration test suite that comes with python-arango. It uses pytest and requires an actual ArangoDB instance.

To run the test suite (use your own host, port and root password):

~$ pip install pytest
~$ git clone https://github.com/arangodb/python-arango.git
~$ cd python-arango
~$ py.test --complete --host=127.0.0.1 --port=8529 --passwd=passwd

To run the test suite with coverage report:

~$ pip install coverage pytest pytest-cov
~$ git clone https://github.com/arangodb/python-arango.git
~$ cd python-arango
~$ py.test --complete --host=127.0.0.1 --port=8529 --passwd=passwd --cov=kq

As the test suite creates real databases and jobs, it should only be run in development environments.

Documentation

The documentation including the README is written in reStructuredText and uses Sphinx. To build an HTML version on your local machine:

~$ pip install sphinx sphinx_rtd_theme
~$ git clone https://github.com/arangodb/python-arango.git
~$ cd python-arango
~$ python -m sphinx -b html -W docs docs/_build/  # Open build/index.html in a browser

As always, thank you for your contribution!