Contributing

How to Contribute

Twiga is built by volunteers. The workflow is a standard fork and pull request, with two conventions worth reading first.

Before you write code

There is no curated list of starter issues and no good first issue label. The fastest way in is the tech-support channel on the Discord, where you can ask what needs doing. For anything larger, open a GitHub discussion before building it.

The workflow

Fork the repository
When forking, uncheck the option to copy only the main branch. Work happens on development, and without it you will not have that branch.

Branch from development

git checkout development
git checkout -b feature/your-feature-name

Set up the hooks
```
uv sync
source .venv/bin/activate
pre-commit install
```
This is what keeps formatting arguments out of code review.

Commit in the house style

git commit -m "feat(tools): add exam export tool"

Open the pull request against development
Never against main. Pull requests to main are not accepted.

Branch names

Prefix	For
`feature/`	New functionality.
`fix/`	Bug fixes.
`refactor/`	Changes with no behaviour difference.
`chore/`	Maintenance, dependencies, tooling.
`hotfix/`	Urgent production fixes. Branched from main, maintainers only.
`release/`	Version branches, named `release/0.3.0` with no `v`.

Nothing enforces this, and the history contains plenty of exceptions. Follow it anyway.

Commit messages

Conventional Commits:

type(scope): description

[optional body]

[optional footer]

Types are feat, fix, docs, style, refactor, test and chore. The description is a short imperative phrase. Real examples from the repository:

feat(knowledge-graph): implement new node linking algorithm
fix(api): resolve race condition in concurrent request handling
docs(readme): update API usage examples
feat(api)!: revise authentication mechanism

A ! after the scope marks a breaking change, and should be paired with a BREAKING CHANGE: footer explaining what breaks.

Two documents disagree on this

docs/en/CONTRIBUTING.md shows [type]: message with square brackets. Follow docs/en/GIT_GUIDELINES.md instead, which is the detailed specification, matches the tooling configuration, and matches actual commit history. Nothing lints the format either way.

What CI checks

On every pull request:

Check	What runs
pre-commit	Every hook against the whole repository, not just your changes.
tests	`PYTHONPATH=. pytest -v tests/` on Python 3.12.
secret scan	Skipped on pull requests from forks, which is the normal contributor path.

Because the hooks run repository-wide in CI, a pull request can fail on a file you never touched. Run pre-commit run --all-files locally to reproduce it. See Testing & Checks.

Review

Every pull request needs at least one other developer to approve.
CI has to pass before merge.
Keep pull requests small and single purpose. Describe what changed and link the issue.
Rebase your branch on development to stay current, but never rebase a branch someone else is working from.
The branch is deleted after merge.

Stale documentation is a real contribution

This guide was written by reading the code and the repository documentation side by side, and they disagree in a dozen places. Those are small, self-contained pull requests, and they save the next person the same confusion.

The workflow

Fork the repository

When forking, uncheck the option to copy only the main branch. Work happens on development, and without it you will not have that branch.

Branch from development

git checkout development
git checkout -b feature/your-feature-name

Set up the hooks

uv sync
source .venv/bin/activate
pre-commit install

This is what keeps formatting arguments out of code review.

Commit in the house style

git commit -m "feat(tools): add exam export tool"

Open the pull request against development

Never against main. Pull requests to main are not accepted.

Branch names

Prefix

For

feature/

New functionality.

fix/

Bug fixes.

refactor/

Changes with no behaviour difference.

chore/

Maintenance, dependencies, tooling.

hotfix/

Urgent production fixes. Branched from main, maintainers only.

release/

Version branches, named release/0.3.0 with no v.

Nothing enforces this, and the history contains plenty of exceptions. Follow it anyway.

Commit messages

Conventional Commits:

type(scope): description [optional body] [optional footer]

Types are feat, fix, docs, style, refactor, test and chore. The description is a short imperative phrase. Real examples from the repository:

feat(knowledge-graph): implement new node linking algorithm fix(api): resolve race condition in concurrent request handling docs(readme): update API usage examples feat(api)!: revise authentication mechanism

A ! after the scope marks a breaking change, and should be paired with a BREAKING CHANGE: footer explaining what breaks.

Two documents disagree on this

What CI checks

On every pull request:

Check

What runs

pre-commit

Every hook against the whole repository, not just your changes.

tests

PYTHONPATH=. pytest -v tests/ on Python 3.12.

secret scan

Skipped on pull requests from forks, which is the normal contributor path.

Because the hooks run repository-wide in CI, a pull request can fail on a file you never touched. Run pre-commit run --all-files locally to reproduce it. See Testing & Checks.

Review

Every pull request needs at least one other developer to approve.

CI has to pass before merge.

Keep pull requests small and single purpose. Describe what changed and link the issue.

Rebase your branch on development to stay current, but never rebase a branch someone else is working from.

The branch is deleted after merge.

Stale documentation is a real contribution