Contributing Guidelines

Quick Start

Ideas

  • File an issue.
  • Explain why you want the feature. How does it help you? What for do you want the feature?

Bugs

  • File an issue.
  • Ideally, write a failing test and send it as a Pull Request.

Coding

  1. Fork Marvin.
  2. Create a feature branch.
  3. Execute source bin/setup-env
  4. Write tests.
  5. Write code.
  6. test what you created: pytest tests/
  7. Send a Pull Request.
  8. Make sure test coverage didn't drop and all CI builds are passing.

Semantic Release and Conventional Changelog

Releasing of new Marvin versions to Pypi is automatically managed by Semantic Release. Semantic Release makes sure correct version numbers get bumped according to the meaning of your changes once your PR gets merged to master.

To make it work, it's necessary to follow Conventional Commits. That basically means all commit messages in the project should follow a particular format:

<type>: <subject>

Where <type> is:

  • feat - New functionality added
  • fix - Broken functionality fixed
  • perf - Performance improved
  • docs - Documentation added/removed/improved/...
  • chore - Package setup, CI setup, ...
  • refactor - Changes in code, but no changes in behavior
  • test - Tests added/removed/improved/...

In the rare cases when your changes break backwards compatibility, the message must include string BREAKING CHANGE:. That will result in bumping the major version.

Seems hard?

  • See existing commits as a reference
  • A commit-msg git hook validates the format of your messages

Testing

Use pytest tests/ to run all tests on your default Python platform. Use tox to run the tests in latest versions of supported platforms.

To ease development speed tox will execute the tests only in the latest 2.x and 3.x Python versions, however the CI will execute the tests in all supported platforms.

If you believe your changes may not be compatible with a specific Python version, test locally with those other versions. We recommend you use Pyenv

Linting

Marvin uses flake8 to lint both Marvin and tests codebases. Execute flake8 marvin tests.

Documentation

The main documentation is written in Markdown using MkDocs. Marvin uses ReadTheDocs to build and publish the documentation:

Source of the documentation can be found in the docs directory. To run a live preview of the documentation execute:

mkdocs serve

Note

The .github/CONTRIBUTING.md file is a symbolic link to the docs/contributing.md file, where the actual content lives.

This is to be able to serve the same content also as [GitHub contributing guidelines][] when someone opens a Pull Request.

Coverage

Marvin strives for as much test coverage as possible. CodeClimate help us to monitor how successful we are in achieving the goal. If a Pull Request introduces drop in coverage, it won't be accepted unless the author or reviewer provides a good reason why an exception should be made.

The tox command will execute tests with coverage enabled. As a result an HTML report will be generated. You can find it at build/coverage/index.html.