Skip to content

Contributing to BitLogic

Dev loop: setup, branch, format, test, PR.

1. Dev environment (uv)

git clone https://github.com/aplesner/bitlogic.git
cd bitlogic

# Install uv once (if missing):
# curl -LsSf https://astral.sh/uv/install.sh | sh

uv sync --extra cpu --extra dev         # CPU-only
uv sync --extra cu128 --extra dev       # GPU (CUDA 12.8)

uv sync creates .venv/, resolves the lock, and installs BitLogic in editable mode plus pytest / ruff. Activate with source .venv/bin/activate, or run tools via uv run <cmd>.

2. Branch

git fetch origin
git checkout -b feature/my-change origin/main
Prefix Example Use case
feature/ feature/add-attention-node new features
bugfix/ bugfix/issue-42-fix-leak bug fixes (link issue if any)
hotfix/ hotfix/critical-crash urgent production fixes
docs/ docs/update-install documentation
refactor/ refactor/simplify-registry refactors
test/ test/add-node-tests tests only
chore/ chore/update-deps maintenance

Lowercase, hyphen-separated, short.

3. Code style

Ruff handles both linting and formatting (black-compatible). Config lives in [tool.ruff] / [tool.ruff.lint] / [tool.ruff.format] in pyproject.toml. Line length 100, target Python 3.10+.

uv run ruff format .              # format
uv run ruff check . --fix         # lint + autofix
uv run ruff check .               # what CI runs
uv run ruff format --check .

Type hints: modern syntax (X | None, list[int]). Docstrings: Google style (Args:, Returns:, Raises:, Example:) — mkdocstrings renders them on the docs site.

4. Tests

uv run pytest

No custom markers — everything runs every time. tests/unit/ for per-module tests, tests/integration/ for end-to-end. CI runs the same command on Python 3.11 and enforces --cov-fail-under=65.

5. Version bumps (releases only)

Semantic versioning. pyproject.toml is the source of truth; bitlogic.__version__ is resolved at import via importlib.metadata.

uv version --bump patch           # 1.2.3 → 1.2.4
uv version --bump minor           # 1.2.3 → 1.3.0
uv version --bump major           # 1.2.3 → 2.0.0

NEW=$(uv version --short)
git commit -am "Bump version: $NEW"
git tag "v$NEW"
git push --follow-tags

6. CI

Three workflows under .github/workflows/:

  • tests.yml — uv run pytest --cov=bitlogic --cov-fail-under=65 on Python 3.11. Blocks merge on failure.
  • format.yml — ruff format --check + ruff check. Non-blocking; posts a PR comment with the fix command.
  • pages.yml — builds + deploys the MkDocs site on push to main (uses --strict, so broken refs fail the build).

7. Before you open a PR

  1. uv run ruff format . && uv run ruff check . --fix
  2. uv run pytest
  3. uv run mkdocs build --strict (if you touched docs or public API)
  4. Open the PR against main.

Editor integration

VS Code — install the Ruff extension and add to .vscode/settings.json:

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": { "source.organizeImports": "explicit" }
  }
}

PyCharm — install the Ruff plugin and enable "Run ruff on save" in Settings → Tools → Actions on Save.