How to Contribute

Join the ObjectQuel community and help make it better. Learn how to contribute code, documentation, and improvements to the project.

Getting Started

Set up your development environment:

# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/quellabs/objectquel.git
cd objectquel

# Install dependencies
composer update

# Set up environment
cp .env.example .env

Development Workflow

Follow our development process:

# Create a feature branch
git checkout -b feature/amazing-feature

# Make your changes
# Add tests for new functionality
# Update documentation if needed

# Run the test suite
./vendor/bin/pest

# Run code style checks
./vendor/bin/php-cs-fixer fix --dry-run

# Fix code style issues
./vendor/bin/php-cs-fixer fix

# Commit your changes
git add .
git commit -m "Add amazing new feature"

# Push to your fork
git push origin feature/amazing-feature

# Create a Pull Request on GitHub

Code Style Guidelines

ObjectQuel follows PSR-12 Extended Coding Style Guide with these key requirements:

  • Use tabs for indentation, not spaces
  • Opening braces for classes and methods go on the same line
  • Always use strict types declaration
  • Follow PascalCase for class names, camelCase for methods and properties
  • Use UPPER_SNAKE_CASE for constants
  • Include complete PHPDoc blocks for all classes and methods

Run ./vendor/bin/php-cs-fixer fix to automatically format your code according to project standards.

Testing Requirements

ObjectQuel uses Pest for testing. All contributions must include appropriate tests:

# Run all tests
./vendor/bin/pest

# Run specific test directories
./vendor/bin/pest tests/Unit
./vendor/bin/pest tests/Feature

# Run tests with coverage
./vendor/bin/pest --coverage

# Run tests in parallel (faster)
./vendor/bin/pest --parallel

Test Coverage Requirements

  • New features: 90%+ coverage required
  • Bug fixes: Test for the specific bug + regression tests
  • Refactoring: Maintain or improve existing coverage
  • Critical features: 100% coverage required

Generate coverage reports with ./vendor/bin/pest --coverage --min=80

Issue Reporting

Report bugs and request features effectively using our templates:

Bug Report Template

  • Expected Behavior: Describe what you expected to happen
  • Actual Behavior: Describe what actually happened
  • Steps to Reproduce: Numbered list of reproduction steps
  • Environment: ObjectQuel version, PHP version, database, OS
  • Additional Context: Error logs, code examples, screenshots

Feature Request Template

  • Feature Description: Clear description of the proposed feature
  • Use Case: Explain why this feature would be useful
  • Proposed Implementation: Optional implementation suggestions
  • Alternatives Considered: Other approaches you've considered

Code Review Process

Participate effectively in the code review process:

As a Contributor

  • Respond to feedback promptly and constructively
  • Make requested changes in new commits (don't force-push after review starts)
  • Be open to suggestions and improvements
  • Ensure all tests pass before requesting review

As a Reviewer

  • Be constructive and specific in feedback
  • Focus on code quality, not personal preferences
  • Test the changes if possible
  • Approve when ready or clearly request changes

Review Checklist

  • Code follows project standards
  • Tests are comprehensive and passing
  • Documentation is updated
  • No performance regressions
  • Security considerations addressed
  • Backwards compatibility maintained

Community Guidelines

Be part of our welcoming community:

Code of Conduct

  • Be respectful and professional
  • Welcome newcomers and help them learn
  • Focus on constructive feedback
  • Assume good intentions
  • Help others learn and grow

Communication Channels

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: Questions and community ideas
  • Stack Overflow: Tag questions with 'objectquel'

Ways to Contribute

  • Fix bugs and add new features
  • Improve documentation and examples
  • Write tutorials and guides
  • Answer questions in the community
  • Review pull requests from other contributors
  • Test new releases and report issues

Release Process

Understanding our release workflow:

Semantic Versioning

We follow MAJOR.MINOR.PATCH versioning (e.g., 2.1.3):

  • MAJOR: Breaking changes that require code updates
  • MINOR: New features that are backwards compatible
  • PATCH: Bug fixes that are backwards compatible

Release Schedule

  • Major releases: Every 12 months
  • Minor releases: Every 3 months
  • Patch releases: As needed for critical bugs

Branch Strategy

  • main: Stable release branch
  • develop: Development branch for upcoming features
  • feature/*: Individual feature branches
  • hotfix/*: Critical bug fixes for immediate release

Getting Help

If you need assistance while contributing:

  • Check the README.md for basic usage and setup
  • Browse existing GitHub Issues for similar problems
  • Start a GitHub Discussion for questions
  • Review the codebase for examples and patterns
  • Ask for help in your pull request if you get stuck

Thank you for considering contributing to ObjectQuel! Your contributions help make the project better for everyone.