Contributingยค
Hello and thank you for considering contributing to cookiecutter-pypackage-instance!
Reading and following these guidelines will help us make the contribution process easy and effective for everyone involved.
This project follows the all-contributors specification. You can read more here.
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
- Fork the repository to your own Github account
- Clone the project to your machine
- Create a branch locally with a succinct but descriptive name
- Commit changes to the branch
- Push changes to your fork
- 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-instance 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-instance 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.