Skip to content

contributing.md

Latest commit

 

History

History
276 lines (193 loc) · 7.01 KB

contributing.md

File metadata and controls

276 lines (193 loc) · 7.01 KB
Raw

Contributing

Help improve auditor-bundle

Thank you for considering contributing to auditor-bundle!

🤝 Ways to Contribute

  • 🐛 Report bugs - Submit issues on GitHub
  • 💡 Suggest features - Open a discussion or issue
  • 📖 Improve documentation - Fix typos, add examples, clarify explanations
  • 🔧 Submit code - Fix bugs or implement new features
  • ⭐ Star the project - Show your support

💻 Code Contributions

All code contributions are made via Pull Requests (PR). Direct commits to the master branch are not allowed.

🚀 Development Setup

  1. Fork the repository on GitHub
  2. Clone your fork locally:
git clone https://github.com/YOUR_USERNAME/auditor-bundle.git
cd auditor-bundle
  1. Install dependencies:
composer install
  1. Create a branch for your changes:
git checkout -b feature/my-new-feature

✅ Running Tests

Quick Tests (Local PHP)

# Run all tests
composer test

# Run tests with coverage
composer test:coverage

# Run tests with testdox output
composer testdox

🐳 Testing with Docker (Recommended)

The project includes a Makefile that allows you to test against different combinations of PHP versions and Symfony versions using Docker containers. This ensures your code works across all supported environments.

Prerequisites:

  • Docker
  • Docker Compose
  • Make

Available Make Targets:

Target Description
tests Run the test suite using PHPUnit
cs-fix Run PHP-CS-Fixer to fix coding standards
phpstan Run PHPStan for static code analysis
help Display available commands and options

Options:

Option Values Default Description
php 8.4, 8.5 8.5 PHP version
sf 8.0 8.0 Symfony version
args Any PHPUnit/tool arguments (varies) Additional arguments

Valid PHP/Symfony Combinations:

PHP Version Symfony Versions
8.4 8.0
8.5 8.0

Examples:

# Show all available commands and options
make help

# Run tests with defaults (PHP 8.5, Symfony 8.0)
make tests

# Run tests with specific PHP version
make tests php=8.4

# Run specific test class
make tests args='--filter=ViewerControllerTest'

# Run tests with coverage
make tests args='--coverage-html=coverage'

Testing Multiple Versions:

Tip

Before submitting a pull request, it's recommended to test against multiple PHP versions:

# Test different PHP versions
make tests php=8.4
make tests php=8.5

🔍 Code Quality

Before submitting, ensure your code passes all quality checks.

Using Composer (Local)

# Run all QA tools
composer qa

# Individual tools:
composer cs-check    # Check code style
composer cs-fix      # Fix code style
composer phpstan     # Static analysis
composer rector      # Automated refactoring suggestions

Using Make (Docker)

# Run PHP-CS-Fixer
make cs-fix

# Run PHPStan
make phpstan

# With specific PHP version
make phpstan php=8.4

# With custom arguments
make cs-fix args='fix --dry-run'

📝 Commit Messages

Write clear, concise commit messages:

  • ✅ Use the present tense ("Add feature" not "Added feature")
  • ✅ Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
  • ✅ Limit the first line to 72 characters
  • ✅ Reference issues and pull requests when relevant

Good examples:

  • Add support for custom viewer templates
  • Fix RoleChecker when no user is authenticated
  • Update documentation for v7 migration

📤 Pull Request Process

  1. ✅ Ensure all tests pass (ideally on multiple PHP/Symfony combinations)
  2. ✅ Run code quality tools (make cs-fix, make phpstan)
  3. 📖 Update documentation if needed
  4. 📤 Submit the pull request
  5. 💬 Respond to review feedback

🤖 Continuous Integration (CI)

When you submit a Pull Request, GitHub Actions will automatically run:

  • PHPUnit tests across the full matrix:
    • PHP versions: 8.4, 8.5
    • Symfony version: 8.0
  • PHP-CS-Fixer for code style validation
  • PHPStan for static analysis
  • Code coverage report

Important

Your PR must pass all CI checks before it can be merged. If a check fails, review the logs to identify and fix the issue.

Tip

Run make tests php=8.4 and make tests php=8.5 locally before pushing to catch compatibility issues early.

✍️ Writing Tests

Tests are highly encouraged and often required for new features or bug fixes:

  • 📁 Place tests in the tests/ directory, mirroring the src/ structure
  • 📝 Use meaningful test method names that describe the behavior being tested
  • ✅ Include both positive and negative test cases
  • 🔍 Test edge cases and error conditions

Test Structure Example:

namespace DH\AuditorBundle\Tests\Controller;

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

final class ViewerControllerTest extends WebTestCase
{
    public function testAuditListIsAccessible(): void
    {
        $client = static::createClient();
        $client->request('GET', '/audit');

        $this->assertResponseIsSuccessful();
    }

    public function testAuditListRequiresAuthentication(): void
    {
        // ...
    }
}

Running Your Tests:

# Run only your new tests
make tests args='--filter=ViewerControllerTest'

# Run with coverage to ensure good test coverage
composer test:coverage

🐛 Reporting Bugs

When reporting bugs, please include:

  1. 📦 auditor-bundle version - composer show damienharper/auditor-bundle
  2. 📦 auditor version - composer show damienharper/auditor
  3. 🐘 PHP version - php -v
  4. 🎵 Symfony version - composer show symfony/framework-bundle
  5. 📋 Steps to reproduce - Minimal code example
  6. ✅ Expected behavior - What should happen
  7. ❌ Actual behavior - What actually happens
  8. 📝 Error messages - Full stack trace if available

💡 Feature Requests

For feature requests:

  1. 🔍 Check existing issues to avoid duplicates
  2. 📝 Describe the use case
  3. 💭 Explain why existing features don't meet your needs
  4. 🔧 Suggest a possible implementation if you have ideas

📖 Documentation Contributions

Documentation lives in the docs/ directory and uses Markdown.

Style Guide

  • ✅ Use clear, simple language
  • ✅ Include code examples
  • ✅ Add internal links to related content
  • ✅ Use standard Markdown tables with pipes
  • ✅ Test all code examples

❓ Questions?

  • Open a GitHub Issue
  • Check existing issues first
  • Be patient - maintainers are volunteers

📜 License

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