Skip to content

How to Contribute to Pcons

Pcons welcomes contributions from the community.

Requirements: Python 3.11+ and uv

Setting Up Your Fork

  1. On GitHub, click the Fork button to create your own fork
  2. Clone your fork: git clone git@github.com:YOUR_USERNAME/pcons.git
  3. Enter the directory: cd pcons
  4. Add upstream remote: git remote add upstream https://github.com/DarkStarSystems/pcons

Setting Up the Development Environment

# Install dependencies and create virtual environment
uv sync

# Verify the setup
uv run pcons --help
uv run pytest

Development Workflow

Create a Branch

git checkout -b my_contribution

Run Tests

uv run pytest

Property Tests

tests/fuzz/ holds property-based tests (Hypothesis): instead of one worked example, they state a rule — de-duplicating flags never separates a flag from its argument, a topological sort always puts dependencies first — and let Hypothesis look for a counterexample.

They run as part of the normal suite, short and with a fixed seed, so make test stays fast and reproducible. The nightly CI job runs a much longer, randomized campaign:

make fuzz    # what CI runs nightly

When one finds a failure it prints a minimized counterexample. Fix the bug, then add that example to the matching unit test file (tests/core/, tests/generators/, ...) — the property keeps searching, the unit test keeps this particular case from coming back.

Run Linter and Type Checker

# Run all checks
make lint

# Or run individually
uv run ruff check pcons/ tests/
uv run mypy pcons/

Format Code

# Auto-format
make fmt

# Or run directly
uv run ruff format pcons/ tests/

Run Tests with Coverage

uv run pytest --cov=pcons --cov-report=html

Commit Guidelines

This project uses conventional commit messages.

Examples: - fix(resolver): handle empty source lists - feat(toolchain): add LLVM/Clang support - docs: update README examples - test: add coverage for Windows paths

Submitting a Pull Request

  1. Push your branch: git push origin my_contribution
  2. On GitHub, open a Pull Request against main
  3. Wait for CI to pass and a maintainer to review

Makefile Targets

make help    # Show available targets
make lint    # Run linters (ruff, mypy)
make fmt     # Format code with ruff
make test    # Run tests with pytest

License

By contributing to pcons, you agree that your contributions will be licensed under the MIT License.