Contributing

Contributions are welcome and greatly appreciated. Please ensure while contributing or interacting with the developers that you follow our Code of Conduct.

Types of Contributions

Report Security Vulnerabilities

If you think you have found a security vulnerability, please email axorl@quine.sh.

Please don’t report it in an GitHub issue or in any other public discourse platform.

Report Bugs and Make Feature Requests

Open an issue in our GitHub Repo.

Write Code

Feel free to look through the GitHub issues for open issues. Anything tagged with “help wanted” is available to fix.

Please ensure new and altered features have tests and are documented with DocStrings.

Write Documentation

We want pybraries users to have a great experience. Documentation is a huge part of Developer Experience.

Feel free to add to and improve the documentation. You can contribute to official pybraries docs, in docstrings, or by writing blog posts.

Small changes to the docs can be made by editing the code on GitHub in the browser and opening a Pull Request (PR).

If making more substantial changes or additions:

When in the docs folder, build the docs with the command:

make html

The built HTML docs will be created in the docs->_build folder.

Check for broken links by running the following command:

make linkcheck

Get Started!

Ready to contribute? Here’s how to set up pybraries for local development.

Fork the quibraries repo on GitHub.

Clone your fork locally:

git clone git@github.com:your_github_username_here/quibraries.git

Install your local copy into a virtual environment.
Create a branch for local development:
```
git checkout -b name-of-your-bugfix-or-feature-branch
```
Now you can make your changes locally.
Install requirements.txt with:
```
pip install -r requirements.txt
```
To ensure code quality we use a few tools as pre-commit hooks, which need to pass.
When you’re done making changes, check that your changes pass the test suite and all pre-commit hooks.:
```
pre-commit run --all-files && pytest .
```

Commit your changes and push your branch to GitHub:

git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature

Submit a Pull Request (PR) through GitHub.

Note, you need a libraries.io API key as an environment variable with the name: ``LIBRARIES_API_KEY=<your_key>` to run the tests successfully`.

To allow logging, you need to have the environment variable set as QB_LOG_ENABLED=True and setup the basic logger to accept the level of messages you want to receive. This can be accomplished by:

import logging
logging.basicConfig(level=logging.DEBUG)

If you are new to contributing to open source, check out this guide by Chalmer Lowe.

Code Quality

We use as described above few tools as pre-commit hooks. Most notably, we use black for code formatting and Flake8 plus Pylint for linting.

Max line length is set to 119 characters and the following warnings/errors are ignored:

E203 - Whitespace before, this is because it conflicts with the black code formatter in some instances.
W503 - Break occurred before a binary operator, this is in the process of being deprecated.

The full list of linters can be seen in the pre-commit-config.yaml file located in the main directory of the project.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

If code was updated, the pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
The code should work for Python 3.10 and higher.

Deploying

The deployments happen automatically upon releasing to the release branch. Few checks happen to ensure that the releases do not cause any mess. Then, we can release simultaneously to both GitHub as well as PyPi though the trusted publishing flow. For more details, please see here.