Contributing to PrompTrek

Thank you for your interest in contributing to PrompTrek! This guide will help you get started with contributing to the project.

🚀 Quick Start for Contributors

Prerequisites

Development Setup

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/promptrek.git
cd promptrek
  3. Install development dependencies: 
    # Using uv (recommended)
uv sync

# Or using pip
pip install -e ".[dev]"
  4. Install pre-commit hooks: 
    pre-commit install
  5. Run tests to verify setup: 
    # Using uv
uv run pytest

# Or using pytest directly
pytest

🎯 Ways to Contribute

🐛 Bug Reports

Found a bug? Help us fix it!

  1. Search existing issues to avoid duplicates
  2. Create a new issue using our bug report template
  3. Include detailed information:
    • PrompTrek version
    • Python version
    • Operating system
    • Steps to reproduce
    • Expected vs actual behavior
    • Any error messages

Report a Bug →

💡 Feature Requests

Have an idea for a new feature?

  1. Search existing issues for similar requests
  2. Create a feature request using our template
  3. Describe the use case and expected benefits

Request a Feature →

🔧 Code Contributions

Ready to write some code? Here’s how:

1. Choose an Issue

2. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

3. Make Your Changes

4. Test Your Changes

# Run all tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=promptrek --cov-report=html

# Run linting
uv run black src/ tests/
uv run flake8 src/ tests/
uv run mypy src/

5. Commit Your Changes

We use Conventional Commits:

# Format: type(scope): description
git commit -m "feat(adapters): add support for new editor"
git commit -m "fix(parser): handle edge case in YAML parsing"
git commit -m "docs(readme): update installation instructions"

Commit types:

6. Push and Create Pull Request

git push origin your-branch-name

Then create a pull request on GitHub using our PR template.

📝 Documentation

Documentation improvements are always welcome!

🎨 New Editor Support

Want to add support for a new AI editor?

  1. Research the editor’s prompt format
  2. Create an issue to discuss the implementation
  3. Follow our adapter pattern (see src/promptrek/adapters/)
  4. Add comprehensive tests
  5. Update documentation

🛠 Development Guidelines

Coding Standards

Code Quality

Code Style

We use automated tools to maintain consistent code style:

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Lint code
flake8 src/ tests/ --max-line-length=88

# Type checking
mypy src/

Testing Standards

# Run tests with coverage
pytest --cov=promptrek --cov-report=html --cov-fail-under=90

Project Structure

promptrek/
├── src/
│   └── promptrek/
│       ├── cli/                 # Command-line interface
│       ├── core/                # Core functionality
│       ├── adapters/            # Editor-specific adapters
│       ├── templates/           # Jinja2 templates
│       └── utils/               # Utility functions
├── tests/
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   └── fixtures/                # Test data
├── examples/                    # Example configurations
└── scripts/                     # Development scripts

Adding a New Editor Adapter

  1. Create the adapter class in src/promptrek/adapters/: 
    from .base import EditorAdapter
   
class NewEditorAdapter(EditorAdapter):
    def generate(self, prompt, output_dir, **kwargs):
        # Implementation here
        pass

  2. Register the adapter in src/promptrek/core/registry.py

  3. Add comprehensive tests in tests/unit/adapters/

  4. Update documentation and examples

Testing Your Contributions

Local Testing

# Run specific test file
pytest tests/unit/test_cli.py

# Run tests with verbose output
pytest -v

# Run tests for specific functionality
pytest -k "test_generate"

Integration Testing

# Test CLI commands
promptrek init --output test.promptrek.yaml
promptrek validate test.promptrek.yaml
promptrek generate --all --input test.promptrek.yaml --dry-run

Manual Testing

Test your changes with real-world scenarios:

  1. Create a test project
  2. Generate prompts for multiple editors
  3. Verify the generated files work in actual editors
  4. Test edge cases and error conditions

📋 Pull Request Process

Before Submitting

PR Requirements

Review Process

  1. Automated checks must pass (CI/CD)
  2. Code review by maintainers
  3. Testing on multiple platforms
  4. Documentation review if applicable
  5. Approval and merge

🏷 Release Process

PrompTrek uses semantic versioning and automated releases:

Releases are automated based on conventional commits.

🤝 Community Guidelines

Code of Conduct

Getting Help

Recognition

Contributors are recognized in:

🎯 Contribution Ideas

Good First Issues

Advanced Contributions

Documentation

🔗 Useful Resources

📞 Contact

Thank you for contributing to PrompTrek! Your efforts help make AI-assisted development more accessible and consistent for developers everywhere. 🚀