Contributing¶

If you want to contribute to one of the open source projects you can follow these guidelines.

Help¶

First, check the docs for the specific project. In many cases, you can help in different ways, for example answering questions from others.

Start with a Discussion¶

Before sending a PR, start the conversation with a GitHub Discussion in the corresponding repository.

Explain what you want to achieve, what you want to solve, and what you have in mind.

There's a chance that there's a way to solve it already, or that there are other plans about it that should be considered first.

After that, if one of the team members asks you, you can create a PR with your proposed solution.

Make sure to check that it's a team member asking you and not simply another user.

Developing¶

For the Python projects, follow these steps.

Install Requirements Using uv¶

Install uv.

With uv, install the dependencies with:

$ uv sync

Prek¶

Install prek:

$ uv run prek install

It will run pre-commit hooks, right before you write a commit, they will auto format your code, check for linting errors, etc.

Tests¶

You can run the tests running pytest manually, or running the script:

$ bash scripts/test.sh

Dependencies¶

Note that PRs from non-team members are not allowed to modify pyproject.toml or uv.lock, to prevent supply chain risk.

If you would like to add a new dependency, create a new Discussion to explain why.

Docs¶

Docs Live¶

During local development, you can run the local docs server with live-reloading with:

$ uv run ./scripts/docs.py live

Serving ./site on http://127.0.0.1:8008
Build started

It will serve the documentation on http://127.0.0.1:8008.

That way, you can edit the documentation/source files and see the changes live.

Docs Structure¶

The documentation uses Zensical.

All the documentation is in Markdown format in the directory ./docs.

Many of the tutorials have blocks of code.

In most of the cases, these blocks of code are actual complete applications that can be run as is.

In fact, those blocks of code are not written inside the Markdown, they are Python files in the ./docs_src/ directory.

And those Python files are included/injected in the documentation when generating the site.

In the Markdown files, the include declarations look like this:

{* ./docs_src/first_steps/tutorial001_an_py310.py ln[3:6,8,10:11] *}

They use markdown-include-variants.

Docs for Tests¶

Most of the tests actually run against the example source files in the documentation.

This helps to make sure that:

• The documentation is up-to-date.
• The documentation examples can be run as is.
• Most of the features are covered by the documentation, ensured by test coverage.

Automated Code and AI¶

You are encouraged to use all the tools you want to do your work and contribute as efficiently as possible, this includes AI (LLM) tools, etc. Nevertheless, contributions should have meaningful human intervention, judgement, context, etc.

If the human effort put in a PR, e.g. writing LLM prompts, is less than the effort we would need to put to review it, please don't submit the PR.

Think of it this way: we can already write LLM prompts or run automated tools ourselves, and that would be faster and more secure than reviewing external PRs.

Closing Automated and AI PRs¶

If we see PRs that seem AI generated or automated in similar ways, we'll flag them and close them.

The same applies to comments and descriptions, please don't copy-paste the content generated by an LLM.

Human Effort Denial of Service¶

Using automated tools and AI to submit PRs or comments that we have to carefully review and handle would be the equivalent of a Denial-of-service attack on our human effort.

It would be very little effort from the person submitting the PR (an LLM prompt) that generates a large amount of effort on our side (carefully reviewing code).

Please don't do that.

We'll need to block accounts that spam us with repeated automated PRs or comments.

Use Tools Wisely¶

As Uncle Ben said:

With great power tools comes great responsibility.

Avoid inadvertently doing harm.

You have amazing tools at hand, use them wisely to help effectively.