Contributing

Setting up

To install the dependencies, run:

$ pip install -r requirements.txt

while you have a virtual environment activated.

You are recommended to use pyenv to handle virtual environments and Python versions. That way, you can easily test and debug problems that are specific to one version of Python.

Testing

You can perform an integration test by running pod2gen/__main__.py:

$ python -m pod2gen

When working on this project, you should run the unit tests as well as the integration test, like this:

$ make test

The unit tests reside in pod2gen/tests and are written using the unittest module.

Values

Read Philosophy, Scope and Why the fork? for a run-down on what values/principles lay the foundation for this project. In short, it is important to keep the API as simple as possible.

You must also write unittests as you code, ideally using test-driven development (that is, write a test, observe that the test fails, write code so the test works, observe that the test succeeds, write a new test and so on). That way, you know that the tests actually contribute and you get to think about how the API will look before you tackle the problem head-on.

Make sure you update pod2gen/__main__.py so it still works, and use your new functionality there if it makes sense.

You must also make sure you update any relevant documentation. Remember that the documentation includes lots of examples and also describes the API independently from docstring comments in the code itself.

Pull requests in which the unittests and documentation are NOT up to date with the code will NOT be accepted.

Lastly, a single commit shouldn’t include more changes than it needs. It’s better to do a big change in small steps, each of which is one commit. Explain the impact of your changes in the commit message.

The Workflow

  1. Check out our GitLab Issues.

    • Find the issue you wish to work on.

    • Add your issue if it’s not already there.

    • Discuss the issue and get feedback on your proposed solution. Don’t waste time on a solution that might not be accepted!

  2. Work on the issue in a separate branch which follows the name scheme #<issue-number>-<brief-description> in your own fork.

  3. Push the branch.

  4. Do the work.

  5. When you’re done and you’ve updated the documentation and tests (see above), create a pull request which references the issue.

  6. Wait for the pull request to be reviewed. Keep an eye on your inbox or your GitLab notifications, in case of objections or feedback that must be taken into consideration.

Linting

pod2gen uses Black (version 21.8b0) for linting and Isort (version 5.9.3) for organizing python imports.

It is import to use the mentioned versions above to make sure that the code formatting stay coherent. Please make sure to always lint your code using isort and black before committing code.

In order to make sure that black and isort work well together, a .isort.cfg file is added to the root directory with the following content:

[settings]
profile=black