Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
170 lines (143 loc) · 7.16 KB

CONTRIBUTING.md

File metadata and controls

170 lines (143 loc) · 7.16 KB

Contributing to PDD CLI

Thank you for considering contributing to PDD CLI! This guide summarizes how we work and how you can have impact quickly.

Overview

  • PDD (Prompt‑Driven Development) treats prompts as the source of truth; code is regenerated from prompts and tests accumulate over time.
  • We use Discord for real‑time discussion and GitHub Issues/Discussions for async collaboration.
  • All contributions matter: docs, tests, bug fixes, features, tooling, and onboarding support.

Core Philosophy

  • Prompt is the source of truth.
  • Regenerate rather than patch code manually when possible.
  • Keep spec/README, prompts, code, examples, and tests in sync.
  • Tests accumulate: append tests; don’t regenerate or remove them.
  • Modular prompt graph: prompts compose via includes.

The “Dev Unit”

Each complete change ideally includes four elements:

  • Prompt: defines behavior (some compile‑time prompts are being open‑sourced over time).
  • Code: generated/updated implementation.
  • Example interface: usage examples that enable prompt composability.
  • Tests: appended to relevant test files to reproduce bugs or validate features.

Contribution Workflow

  1. Get set up
  • Fork the repository and clone your fork.
  • Install prerequisites; prefer the PDD setup script when available (v0.57+). Docker is optional but helpful for consistency.
  • Configure LLM/API keys as needed.
  1. Choose work
  • Browse GitHub Issues or open one describing your bug/feature/idea.
  • Use Discord for quick feedback; GitHub Discussions for async/archival.
  1. Define and test
  • For features: update README/spec first; it drives prompts and implementation.
  • For bugs: write a failing test that reproduces the issue before fixing.
  • Append tests in the appropriate module under tests/.
  1. Implement
  • Prefer using PDD to regenerate code from prompts.
  • If editing code directly, run pdd update to sync changes back into prompts (until all prompts are public, maintainers may help sync).
  • Keep example interfaces updated to reflect new/changed behavior.
  • Useful prompt tags when needed: <include>, <pdv>, <shell>, <web>.
  1. Submit a PR
  • Include the four dev‑unit elements when applicable: prompt, code, example, tests.
  • Reference the related issue and summarize approach and implications.
  • Expect review feedback; iterate until approved and merged.

Communication Channels

  • Discord: primary real‑time venue for questions and design discussions.
  • GitHub Issues: track work, propose ideas, report bugs.
  • GitHub Discussions: longer‑form, async conversations and announcements.

Development Setup

  1. Clone your fork: 
    git clone https://github.com/your-username/pdd.git
cd pdd
  2. Create and activate a Conda environment (recommended): 
    conda create -n pdd python=3.12
conda activate pdd
  3. Install dependencies in editable mode with dev extras: 
    pip install -e .[dev]
  4. Optional: Use Docker for reproducible environments, especially for tricky, environment‑dependent bugs.

Running Tests

Run the test suite before submitting changes:

pytest

With coverage reporting:

pytest --cov=pdd

Continuous Integration

Unit tests run automatically on every PR and push to main via GitHub Actions. The CI workflow:

  • Runs ~3,000 mock-based unit tests in ~3 minutes using parallel execution (pytest-xdist)
  • Excludes tests marked integration, e2e, or real (these require paid API keys)
  • Excludes a small number of tests that require platform-specific tools (e.g. zsh) or make unmocked network calls

If CI fails on your PR, check the workflow output for the specific test failures. Most unit tests use mocks and should pass without any API keys configured.

To run the same subset locally:

pip install pytest-timeout
pytest tests/ -m "not integration and not e2e and not real" --timeout=60

Adding/Updating Tests (Strongly Encouraged)

  • Location: put tests in tests/ using pytest style (test_*.py).
  • Red/green: commit a failing test first, then the fix that makes it pass.
  • Regression focus: ensure the test fails without your change and passes with it.
  • Coverage: exercise public APIs and edge cases related to your change.

Building the Package

To build wheel and sdist:

  1. Install build tools: 
    pip install build
  2. Build from project root: 
    python -m build

Artifacts appear in dist/.

Tools for Contributors

  • IDEs: Cursor (great prompt autocomplete) or VS Code (PDD extension for syntax highlighting).
  • CLIs: Kodex CLI and other LLM CLIs (e.g., Gemini); use what works for you.
  • Docker: for reproducible bug reports and dev environments.

Key PDD CLI Parameters

  • --strength: model strength/size.
  • --temperature: creativity vs. determinism.
  • --time: thinking tokens/budget.

Known Limitations and Roadmap

  • Some compile‑time prompts are not yet open‑sourced (pending investor approval). Until then, code edits may require maintainers to sync prompts.
  • pdd sync is alpha and currently focuses within a dev unit; cross‑unit syncing is planned.
  • Contributors have varying LLM/model access, leading to variability; a future cloud version will standardize models and auto‑optimize cost/params.

Good First Contributions

  • Documentation improvements (clarity, setup steps, examples).
  • Tests that reproduce a bug you hit.
  • Small bug fixes with accompanying tests.
  • Issue triage and creating well‑scoped issues.
  • Dockerfile or setup enhancements.
  • “Hello World” example: validate setup and try syncing/regenerating.

Quality Tips

  • Start with the spec: update README for feature changes.
  • Discuss early in Discord/Issues to avoid rework and align on approach.
  • Keep PRs focused and small; include tests.
  • Use Docker for environment‑dependent bugs.
  • Note parameters used (--strength, --temperature, --time) if relevant to reproducibility.

Community and Support

  • Setup help is available; “setup parties” are encouraged.
  • Share user testimonials (short video) if PDD helps you.
  • Participate in meetups and related community events when possible.

Publishing a Release (Maintainers)

  1. Ensure build artifacts are up‑to‑date (see Building the Package).
  2. Install Twine if needed: 
    pip install twine
  3. Upload to PyPI with credentials: 
    twine upload dist/*

Pull Request Process

  1. Remove stray build/install artifacts before committing.
  2. Update README.md if you change the interface (env vars, commands, parameters, examples).
  3. Bump the version in pyproject.toml (SemVer) when appropriate; reflect changes in README.md as needed.
  4. Include tests in tests/ that demonstrate the issue/feature and verify the behavior.
  5. Aim to include dev‑unit elements (prompt/code/example/tests) when applicable.
  6. Make sure CI passes (unit tests). If your change affects modules that have integration/LLM tests, run those locally for the impacted areas before marking your PR ready. You do not need to run the full integration suite -- maintainers will do that before merging.
  7. Seek two maintainer reviews prior to merge, or request a reviewer to merge if you lack permissions.

Thank you for your contributions!