Contributing#

Thank you for helping improve the bundled presets and tooling for pc-init.

Development setup#

git clone https://github.com/cleder/gpc-init.git
cd gpc-init
uv sync
uv tool install prek
prek install

Repository layout#

lang/<id>/preset.yaml # language presets (--lang)
framework/<id>/preset.yaml # framework presets (--framework)
gpc_init/ # Python package source
tests/ # pytest test suite

Contributing a preset#

Adding or updating a hook#

Each preset is a standalone preset.yaml file that follows the pre-commit config format.
Every hook (by id) MUST have a description explaining what it does — a name is encouraged too, but description is what makes generated .pre-commit-config.yaml files self-documenting and is not optional.
A language preset looks like this:

---
repos:
  - repo: https://github.com/example/hook
    rev: v1.2.3
    hooks:
      - id: hook-id
        name: Example hook
        description: What this hook does

Framework presets may additionally declare which languages and frameworks they recommend:

---
recommended:
  lang:
    - py
  framework:
    - git
repos:
  - ...

Scope rule#

One PR must touch exactly one language or framework preset.
If you want to update both lang/py/preset.yaml and framework/django/preset.yaml, open two separate PRs.

Validation steps#

Run all four commands against the preset file before opening a PR.
CI enforces the same checks and will fail if they are skipped.

pre-commit validate-config lang/<id>/preset.yaml
pre-commit autoupdate -c lang/<id>/preset.yaml

prek validate-config lang/<id>/preset.yaml
prek autoupdate -c lang/<id>/preset.yaml

After running autoupdate, commit the file if any revisions changed.

To validate and update every preset at once:

find . -name "preset*.yaml" | xargs -I{} pre-commit validate-config {}
find . -name "preset*.yaml" | xargs -I{} pre-commit autoupdate -c {}

find . -name "preset*.yaml" | xargs -I{} prek validate-config {}
find . -name "preset*.yaml" | xargs -I{} prek autoupdate -c {}

Just Runner#

The repository includes a .justfile for using the just runner framework.
You can install just with uv.

uv tool install rust-just

Once you have this installed you can use just to see the available recipes.

❱ just
just --list
Available recipes:
    awesome
    default
    test
    update target="all" type="lang"
    validate target="all" type="lang"

validate and update both take an optional target (a language or framework alias, defaulting to all) and type (lang or framework, defaulting to lang).
This lets you validate and/or update a given preset in a concise manner: just provide the alias, and, for framework presets, the type.

❱ just validate py
Validating py ...
success: All configs are valid
success: All configs are valid

❱ just update py
Autoupdating py...
[https://github.com/MarcoGorelli/absolufy-imports] already up to date!
[https://github.com/astral-sh/ruff-pre-commit] updating v0.15.19 -> v0.15.20
[https://github.com/abravalheri/validate-pyproject] already up to date!
...

For a framework preset, pass framework as the second argument, e.g. just validate django framework.

To validate or update every preset at once, omit the target (or pass all):

just validate
just update

Hook quality bar#

Only include hooks that are publicly available, actively maintained, and add clear value over hooks already in the preset.
Every hook MUST have a description, harvested from its own .pre-commit-hooks.yaml where possible.

Running the CLI locally#

After uv sync, run the CLI directly without installing:

uv run pc-init --help
uv run pc-init --lang=py --framework=django

Or install it into the project venv once:

uv pip install -e .
pc-init --help

Contributing to the Python code#

Run the test suite and static checks before opening a PR:

just test

which will run:

uv run pytest tests --cov=gpc_init tests
uv run complexipy --failed gpc_init
uv run ruff check gpc_init tests
uv run ruff format gpc_init tests
uv run pyrefly check gpc_init tests
uv run ty check gpc_init tests

Submitting a pull request#

Fill in the PR description and complete every item in the pre-submission checklist before requesting review.
Incomplete checklists will not be merged.