contributing.md

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

3. Install dependencies:

composer install

4. 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:

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

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.