How to Contribute to Pcons¶

Pcons welcomes contributions from the community.

Requirements: Python 3.11+ and uv

Setting Up Your Fork¶

On GitHub, click the Fork button to create your own fork
Clone your fork: git clone git@github.com:YOUR_USERNAME/pcons.git
Enter the directory: cd pcons
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

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¶

Push your branch: git push origin my_contribution
On GitHub, open a Pull Request against main
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.