Skip to content

🍪 Contributing

bigtree is a tree implementation package for Python. It integrates with Python lists, dictionaries, pandas and polars DataFrame.

Thank you for taking the time to contribute. Contributing to this package is an excellent opportunity to dive into tree implementations.

Set Up

First, fork the repository and clone the forked repository.

$ git clone git@github.com:<your-username>/bigtree.git

Next, create a virtual environment and activate it.

$ conda create -n bigtree_venv python=3.10
$ conda activate bigtree_venv

$ python -m venv .venv
$ source .venv/bin/activate

To check if it worked,

$ which pip
/<some directory>/envs/bigtree_venv/bin/pip

$ which pip
/<current directory>/.venv/bin/pip

From the project folder, install the required python packages locally in editable mode and set up pre-commit checks.

$ python -m pip install -e ".[all]"
$ python -m pip install pre-commit
$ pre-commit install

Developing

After making your changes, create a new branch, add and commit your changed files. In this example, let's assume the changed file is README.md. If there are any pre-commit changes or comments, do modify, re-add and re-commit your files.

$ git checkout -b chore/update-readme
$ git add README.md
$ git commit -m "chore: updated README"

Push your changes to your created branch and create a pull request from your fork.

$ git push origin chore/update-readme

Testing

If there are changes related to code, make sure to add or update the tests accordingly. Run the following lines of code and ensure the unit tests pass and the code coverage is 100%.

$ python -m pip install pytest pytest-benchmark pytest-cov coverage
$ pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=bigtree

Documentation

If there are changes related to code, make sure to add or update the documentations and docstrings accordingly.

For documentation, bigtree uses mkdocs for documentation and previews can be viewed by running the following lines of code.

$ python -m pip install hatch
$ hatch run mkdocs:build
$ hatch run mkdocs:serve

For docstrings, ensure that the description is most updated and existing, added, or modified sample code examples in docstring still work. Run the following lines of code to generate the coverage report and test report for docstrings. Refer to the console log for information on the file location of the reports.

$ python -m pip install hatch
$ hatch run docs:coverage
$ hatch run docs:doctest

Consequent Changes

Please open an issue to discuss important changes before embarking on an implementation.