Contributing to PR Cat#

Thank you for your interest in contributing to PR Cat! We appreciate your time and effort in helping improve this open source engineering analytics tool.

🎯 Project Philosophy#

PR Cat is designed to be a self-hosted, transparent alternative to proprietary engineering analytics tools. Our focus is on:

Transparency: All algorithms and calculations are open for inspection
Self-hosting: Your data stays on your infrastructure
Engineering health: Metrics that encourage collaboration, not surveillance
Simplicity: Tools that actually help teams, not corporate dashboards

🚀 How to Contribute#

1. Issues and Discussions#

Bug Reports: Found a bug? Please open an issue with detailed reproduction steps
Feature Requests: Have an idea? Start a discussion to gauge community interest
Questions: Use GitHub Discussions for questions about usage, deployment, or architecture

2. Pull Requests#

We welcome pull requests for:

Bug fixes: Clear, focused fixes with test coverage
Documentation improvements: Better docs help everyone
Performance optimizations: Faster is better
Small feature additions: That align with the project philosophy

Before submitting a PR:#

Open an issue first for any significant changes
Fork the repository and create a feature branch
Write tests for new functionality
Update documentation as needed
Follow the existing code style and conventions

PR Guidelines:#

Keep PRs focused and atomic (one feature/fix per PR)
Write clear commit messages
Include tests for new functionality
Update relevant documentation
Be prepared to iterate based on feedback

🔧 Development Setup#

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

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your configuration

# Run development server
pnpm dev

📋 Code Standards#

TypeScript: All new code should be properly typed
ESLint: Follow the existing linting rules
Prettier: Code formatting is handled automatically
Tests: Write tests for new functionality
Documentation: Update docs for user-facing changes

🎛️ Decision Making#

Important: @vorcigernix is the sole maintainer and has final authority over all pull request decisions in this repository. This includes:

What features are accepted
Code quality standards
Architecture decisions
Release timing
Project direction

This approach ensures:

Consistent vision: The project maintains its focus and philosophy
Quality control: All changes align with the project's goals
Timely decisions: No committee paralysis

🍴 Forking is Encouraged!#

Your needs might be different from ours, and that's perfectly fine!

If your feature request or approach doesn't align with the main project's direction, we strongly encourage you to fork the repository. This is the beauty of open source:

Fork freely: Create your own version with your specific needs
Modify anything: Change the UI, add features, integrate with different tools
Share your fork: Others might have similar needs
No hard feelings: Forks are a feature, not a bug

Popular reasons to fork:#

Different UI/UX preferences
Integration with proprietary tools
Industry-specific metrics
Different deployment strategies
Alternative tech stack preferences

🤝 Community Guidelines#

Be respectful: Treat all contributors with kindness and respect
Be constructive: Provide helpful feedback and suggestions
Be patient: Reviews and responses may take time
Be understanding: Not every idea will be accepted, and that's okay

📝 License#

By contributing to PR Cat, you agree that your contributions will be licensed under the same MIT License that covers the project.

🆘 Getting Help#

Documentation: Check the docs directory
Discussions: Use GitHub Discussions for questions
Issues: Search existing issues before creating new ones

🙏 Recognition#

All contributors are valued and will be recognized in our release notes and contributor lists. Your efforts help make PR Cat better for everyone!

Remember: The goal is to build the best self-hosted engineering analytics tool possible. Sometimes that means saying no to good ideas that don't fit the vision. When that happens, forking is not just acceptable—it's encouraged! 🚀