This document provides comprehensive guidelines for contributing to PromptKit.

Developer Certificate of Origin (DCO)

This project uses the Developer Certificate of Origin (DCO) to ensure that contributors have the right to submit their contributions. By making a contribution to this project, you certify that:

  1. The contribution was created in whole or in part by you and you have the right to submit it under the open source license indicated in the file; or
  2. The contribution is based upon previous work that, to the best of your knowledge, is covered under an appropriate open source license and you have the right under that license to submit that work with modifications, whether created in whole or in part by you, under the same open source license (unless you are permitted to submit under a different license), as indicated in the file; or
  3. The contribution was provided directly to you by some other person who certified (1), (2) or (3) and you have not modified it.

Signing Your Commits

To sign off on your commits, add the -s flag to your git commit command:

git commit -s -m "Your commit message"

This adds a “Signed-off-by” line to your commit message:

Signed-off-by: Your Name <your.email@example.com>

How to Contribute

Reporting Bugs

Suggesting Features

Submitting Changes

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/your-feature-name
  3. Make your changes
  4. Write/update tests
  5. Commit your changes: Use clear, descriptive commit messages with -s flag for DCO
  6. Pre-commit checks run automatically (linting, tests, coverage on changed code)
  7. Push to your fork: git push origin feature/your-feature-name
  8. Open a Pull Request

Tip: Run make verify before pushing to ensure CI will pass.

Development Setup

Prerequisites

Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/PromptKit.git
cd PromptKit

# Install dependencies
make install

# Install development tools
brew install golangci-lint
pip3 install diff-cover

# Set up pre-commit hooks
./scripts/install-hooks.sh

# Run tests
make test

# Build all components
make build

See the Pre-Commit Hooks guide for details on automated code quality checks.

Project Structure

PromptKit/
├── runtime/          # Core runtime components
├── pkg/              # Shared packages
├── tools/arena/      # PromptKit Arena CLI
├── tools/packc/      # Pack Compiler tool
├── sdk/              # PromptKit SDK
├── examples/         # Example configurations
└── docs/             # Documentation

Component-Specific Contribution Guidelines

Arena CLI (tools/arena/)

Focus: Testing framework for LLM applications

Key Areas for Contribution:

Testing Arena Changes:

# Build Arena
make build-arena

# Run Arena tests
cd tools/arena && go test ./...

# Test with example scenarios
./bin/promptarena run examples/customer-support/arena.yaml

PackC CLI (tools/packc/)

Focus: Prompt packaging and compilation tool

Key Areas for Contribution:

Testing PackC Changes:

# Build PackC
make build-packc

# Run PackC tests
cd tools/packc && go test ./...

# Test pack compilation
./bin/packc build examples/customer-support/packs/

SDK (sdk/)

Focus: Production-ready library for deploying LLM applications

Key Areas for Contribution:

Testing SDK Changes:

# Build and test SDK
cd sdk && go test ./...

# Run integration tests
cd sdk && go test -tags=integration ./...

# Test with examples
cd examples/customer-support && go run main.go

Runtime (runtime/)

Focus: Core engine and shared components

Key Areas for Contribution:

Testing Runtime Changes:

# Build and test runtime
cd runtime && go test ./...

# Run comprehensive tests
make test

# Check coverage
make coverage

Coding Guidelines

Go Code Style

Testing

Documentation

Pull Request Process

  1. Ensure CI passes - All tests and linter checks must pass
  2. Update documentation - README, examples, inline docs
  3. Add changelog entry - Describe your changes
  4. Request review - Tag maintainers (see .github/CODEOWNERS)
  5. Address feedback - Respond to review comments
  6. Resolve all conversations - All review comments must be marked as resolved
  7. Sign commits - Use git commit -s for DCO compliance
  8. Keep branch updated - Rebase or merge with latest main
  9. Squash merge - Maintains clean commit history (preferred)

Note: The main branch is protected. See the DevOps documentation for details on branch protection and CI/CD pipelines.

Release Process

Maintainers handle releases:

  1. Update version numbers
  2. Update CHANGELOG.md
  3. Create git tag
  4. Build and test release artifacts
  5. Publish to GitHub releases

Questions?

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.