How To Contribute

First off, thank you for considering contributing to forge! It’s people like you who make it such a great tool for everyone.

This document intends to make contribution more accessible by codifying tribal knowledge and expectations. Don’t be afraid to open half-finished PRs, and ask questions if something is unclear!

Workflow

  • No contribution is too small! Please submit as many fixes for typos and grammar bloopers as you can!
  • Try to limit each pull request to one change only.
  • Always add tests and docs for your code. This is a hard rule; patches with missing tests or documentation can’t be merged.
  • Make sure your changes pass our CI. You won’t get any feedback until it’s green unless you ask for it.
  • Once you’ve addressed review feedback, make sure to bump the pull request with a short note, so we know you’re done.

Code

  • Obey PEP 8 and PEP 257. We use the """-on-separate-lines style for docstrings:

    def func(x):
    """
    Do something.

    :param str x: A very important parameter.

    :rtype: str
    """

  • If you add or change public APIs, tag the docstring using ..  versionadded:: 16.0.0 WHAT or ..  versionchanged:: 16.2.0 WHAT.

  • Prefer double quotes (") over single quotes (') unless the string contains double quotes itself.

Tests

  • Write your asserts as actual == expected to line them up nicely:

    x = f()

assert x.some_attribute == 42
assert x._a_private_attribute == 'foo'

  • To run the test suite, all you need is a recent tox. It will ensure the test suite runs with all dependencies against all Python versions just as it will on Travis CI.

  • Write good test docstrings.

Documentation

  • Use semantic newlines in reStructuredText files (files ending in .rst):

    This is a sentence.
This is another sentence.

  • If you start a new section, add two blank lines before and one blank line after the header, except if two headers follow immediately after each other:

    Last line of previous section.


Header of New Top Section
-------------------------

Header of New Section
^^^^^^^^^^^^^^^^^^^^^

First line of new section.

  • If you add a new feature, demonstrate its awesomeness on the examples page!

Local Development Environment

You can (and should) run our test suite using tox. However, you’ll probably want a more traditional environment as well. We highly recommend to develop using the latest Python 3 release because forge tries to take advantage of modern features whenever possible.

First create a virtual environment.

Next, get an up to date checkout of the forge repository:

$ git checkout git@github.com:dfee/forge.git

Change into the newly created directory and after activating your virtual environment install an editable version of forge along with its tests and docs requirements:

$ cd forge
$ pip install -e .[dev]

At this point,

$ python -m pytest

should work and pass, as should:

$ cd docs
$ make html

The built documentation can then be found in docs/_build/html/.

Governance

forge is maintained by Devin Fee, who welcomes any and all help. If you’d like to help, just get a pull request merged and ask to be added in the very same pull request!

Thank you for contributing to forge!