Contributing
Contributing to FOSS Projects¶
Contributing to open source is easier than most people may think. It's just matter of learning a couple of basic tools and concepts. This guide will show some good practices that most FOSS (free and open source software) follow.
Submiting issues¶
Before sending new issues:
- Are you on the latest version?
- Have you tried older versions?
- Have you searched for old related issues?
- Have you tried the project's mailing list, IRC channel, etc.?
- If nothing worked for you, It's time to create an issue report
Writing a meaningful issue report¶
- Which version of the interpreter are you using?
- Which operating system are you using?
- Which version (tag) of this project are you using?
- What are the steps to reproduce the issue?
Contributing changes¶
Branching¶
- It's important to make your changes on a new branch. This makes easy for the maintainers to add your changes into the main project.
- Always branch off from the main/development branch. Ask if you are not sure.
Code formating¶
- Follow the style of the main repository (e.g. PEP-8). Consistency is the key, always ask if you are not sure.
Documenting¶
- Documenting a project relies on some sort of tool (mkdocs, sphinx, pdoc3, etc.), python projects use docstrings to help making this process easier. There's a plenty of docstring styles out there (e.g. Google, Numpy, etc.). Just follow the style of the project you're working on and ask if you're not sure.
Testing¶
- Any good project include tests, if you are working on a bugfix, strive to achieve 100% code coverage and keep diverse set of unit tests using whatever package the project rely on (e.g. Pytest, Behave, Xdoctest, etc.).
Workflow example¶
The following workflow is specific for this project and might not work for other FOSS
Preparing your Branch¶
- Click the button
Fork
on Github. This will create a project with same name inside your repository list - Clone the forked repo:
git clone git@github.com:USERNAME/PROJECT_NAME
- On terminal type:
cd PROJECT_NAME
- Create a branch:
git checkout -b BRANCH_NAME
Creating commits¶
- Install the development requirements:
pip install -r dev-requirements.txt
- Install the project dependencies under a poetry virtual environment:
poetry install
- Activate poetry shell:
poetry shell
- Make your changes
- Run tests, coverage report and pre-commit checks:
nox
- Repeat steps
4
and5
until all tests passed - Commit the changes:
gitmoji --commit
Creating Pull Requests¶
- Push your changes to the forked repo:
git push
- Go to Github website and click the button
Pull request
- Write a description that explains the changes you've done and steps to reproduce
- Click submit
- Invite maintainers to review your code