Skip to content

Contributing¤

Hello and thank you for considering contributing to cookiecutter-pypackage!

Reading and following these guidelines will help us make the contribution process easy and effective for everyone involved.

Code of Conduct¤

By participating and contributing to this project, you agree to uphold our Code of Conduct.

Getting Help¤

In case all you need is an answer to a question, please refrain from opening an issue and instead visit the project's discussion page.

Getting Started¤

Contributions are made to this repository via Issues and Pull Requests (PRs). A few general guidelines that cover both:

  • Search for existing Issues and PRs before creating your own.
  • We work hard to make sure issues are handled in a timely manner but, depending on the impact, it could take a while to investigate the root cause. A friendly ping in the comment thread to the submitter or a contributor can help draw attention if your issue is blocking.

Issues¤

Issues should be used to report problems with the library or request a new feature or documentation change. When you create a new Issue, a template will be loaded that will guide you through collecting and providing the required information.

If you find an Issue that addresses the problem you're having, please add your own reproduction information to the existing issue rather than creating a new one. Adding a reaction can also help in indicating to our maintainers that a particular problem is affecting more than just the reporter.

Pull Requests¤

PRs can be a quick way to get your fix or improvement slated for the next release. In general, PRs should:

  • Only fix/add the functionality in question OR address wide-spread whitespace/style issues, not both.
  • Address a single concern in the least number of changed lines as possible.
  • Be accompanied by a complete Pull Request template (loaded automatically when a PR is created).
  • Add unit or integration tests for added or changed functionality.
  • Any code related changes should be accompanied by corresponding changes to the project's documentation.
  • If your pull request introduces a new feature, the corresponding README section must be updated to reflect this.
  • Write clear, concise commit message(s) using the Conventional Commits format. Why?
  • This project only accepts pull requests related to open issues. In case there is no relevant open issue, feel free to create one.

For changes that address core functionality or would require breaking changes (e.g. a major release), it's best to open an Issue to discuss your proposal first. This is not required but can save time creating and reviewing changes.

In general, we follow the "fork-and-pull" Git workflow

  1. Fork the repository to your own Github account
  2. Clone the project to your machine
  3. Create a branch locally with a succinct but descriptive name
  4. Commit changes to the branch
  5. Push changes to your fork
  6. Open a PR in our repository and follow the PR template so that we can efficiently review the changes

Setting up a local development environment¤

The following sections assume that you have already locally cloned the repository.

Installing Poetry¤

The cookiecutter-pypackage project utilizes the Poetry Python package manager. Having installed Poetry in the global namespace you may now run poetry shell to create a brand new virtual environment and poetry install, in order to install the project's dependencies (development dependencies as well).

Installing pre-commit hooks¤

The project utilizes the pre-commit framework. Having created a virtual environment and installed the required dependencies, you may run pre-commit install --install-hooks to install the git hook scripts.

Testing via pytest¤

We are using pytest to automate testing on multiple environments.

The test suite can be run using poetry run poe test.

(Optional) Installing pyenv¤

pyenv is used, in the context of the cookiecutter-pypackage project, in order to determine the project's compatibility with various versions of Python. Installing pyenv is not strictly required, but it is recommended.

Having installed pyenv in the global namespace, you may now run the following snippet, in order to install Python 3.7, 3.8 and 3.9, which, at the time of writing this document, are the only Python versions, supported by cookiecutter-pypackage.

pyenv install 3.7.10 3.8.9 3.9.4
pyenv local 3.7.10 3.8.9 3.9.4

Feel free to read more about using pyenv, in the context of poetry, here.

Performing development operations via poethepoet¤

We are using poethepoet, to perform various development oriented tasks.

Formatting, type-checking, running the test suite, as well as a few other operations, can be performed by running poe <task>. Please run poe --help (or poetry run poe --help), to list all available operations.

Documenting your changes¤

cookiecutter-pypackage utilizes MkDocs to build and deploy its documentation to GitHub Pages. The documentation is auto-generated from the python docstrings throughout the source code. As a result, any code related change should be accompanied by a corresponding change to the method's / class's docstring.

Having made your changes, please run poe docs and make sure that no error is being raised on build time. Afterwards, open http://localhost:8000/ in your browser of choice and make sure that the documentation renders correctly.

Writing your commit message¤

The project's version number and Changelog, depend on a consistent commit history. As a result, your commit message's format is extremely important. Before opening a pull request, please make sure that your commits strictly follow the Conventional Commits format].

Creating a pull request¤

Make sure you review our Pull Request Guidelines, before initiating a PR.