Contribution guide¶
Setting up the environment¶
1. Run make install-uv
to install uv if not already installed
1. Run make install
to install all dependencies and pre-commit hooks
Code contributions¶
Workflow¶
Clone your fork locally with git
Make your changes
Run
make lint
to run linters and formatters. This step is optional and will be executed automatically by git before you make a commit, but you may want to run it manually in order to apply fixes automatically by git before you make a commit, but you may want to run it manually in order to apply fixesCommit your changes to git
Push the changes to your fork
Open a pull request. Give the pull request a descriptive title indicating what it changes. If it has a corresponding open issue, the issue number should be included in the title as well. For example a pull request that fixes issue
bug: Increased stack size making it impossible to find needle #100
could be titledfix(#100): Make needles easier to find by applying fire to haystack
Tip
Pull requests and commits all need to follow the Conventional Commit format
Note
To run the integration tests locally, you will need the ODBC Driver for SQL Server, one option is using unixODBC.
Guidelines for writing code¶
All code should be tested. This is enforced via pytest.
All code should be properly formatted. This is enforced via Ruff.
Writing and running tests¶
Todo
Write this section
Project documentation¶
The documentation is located in the /docs
directory and is ReST and
Sphinx. If you’re unfamiliar with any of those,
ReStructuredText primer and
Sphinx quickstart are recommended reads.
Running the docs locally¶
To run or build the docs locally, you need to first install the required dependencies:
make install
Then you can serve the documentation with make docs-serve
, or build them with make docs
.
Creating a new release¶
Set up your environment
Ensure you have the
gh
CLI installed and logged in to GitHub.Switch to the
main
branch.
Install and update dependencies
Run:
make install # Install all dependencies make upgrade # Update dependencies to the latest versions make docs # Verify documentation builds
Bump the version
Run:
make release bump=patch
Use
bump=minor
orbump=major
if you need to bump the minor or major version instead.
Prepare the release
Run:
uv run tools/prepare_release.py -c -i --base v{current_version} {new_version}
Replace
{current_version}
with the current version (e.g.,1.2.3
).Replace
{new_version}
with the new version (e.g.,1.2.4
).Example:
uv run tools/prepare_release.py -c -i --base v1.4.4 1.4.5
Run linters and formatters
Ensure code style compliance:
make lint
Clean up the changelog
Open
docs/changelog.rst
and remove any placeholder comments, such as:<!-- By submitting this pull request, you agree to ... --> <!-- Please add in issue numbers this pull request will close ... -->
Commit the release
Create a new branch:
git checkout -b v{new_version}
Commit the changes:
git commit -am "chore(release): bump to v{new_version}"
Open a pull request
Push the branch and create a PR into
main
.Merge once CI checks pass.
Verify the release draft
Once merged, a draft release will be created under
Releases
on GitHub.Edit and publish it.
Publish to PyPI
Approve the
Latest Release
workflow underActions
to publish the package to PyPI.