Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
222 lines (169 loc) · 5.73 KB

CONTRIBUTING.md

File metadata and controls

222 lines (169 loc) · 5.73 KB
Raw

Contributing Guide

Thank you for your interest in contributing to Password Toggle Bundle! This document provides guidelines for contributing to the project.

Table of contents

Code of Conduct

This project adheres to a code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to hectorfranco@nowo.tech.

How Can I Contribute?

Reporting Bugs

If you find a bug, please:

  1. Check that the bug hasn't already been reported in the issues
  2. Create a new issue with:
    • A descriptive title
    • Steps to reproduce the problem
    • Expected behavior vs. actual behavior
    • PHP, Symfony, and bundle versions
    • Screenshots if relevant

Suggesting Enhancements

Enhancement suggestions are welcome:

  1. Check that the enhancement hasn't already been suggested in the issues
  2. Create a new issue with:
    • A descriptive title
    • Detailed description of the proposed enhancement
    • Use cases and benefits
    • Possible implementations (if you have them)

Contributing Code

Setting Up the Development Environment

  1. Fork the repository on GitHub
  2. Clone your fork: 
    git clone https://github.com/your-username/password-toggle-bundle.git
cd password-toggle-bundle
  3. Install dependencies: 
    # With Docker (recommended)
make install

# Without Docker
composer install

Code Standards

The project follows these standards:

  • PSR-12: PHP code style
  • PHP 8.2+: Modern PHP features
  • Strict type hints: declare(strict_types=1); in all files
  • PHP-CS-Fixer: Used to maintain code consistency

Before committing:

# Install git hooks (strips accidental Cursor co-author trailers from messages)
make setup-hooks

# Verify git history has no Cursor co-author trailers (also runs in release-check)
make check-no-cursor-coauthor
# Check code style
make cs-check
# or
composer cs-check

# Fix code style automatically
make cs-fix
# or
composer cs-fix

Tests

CI requires at least 95% code coverage (MIN_COVERAGE in .github/workflows/ci.yml). All tests must pass before merging. New features should include tests.

# Run all tests
make test
# or
composer test

# Run tests with coverage
make test-coverage
# or
composer test-coverage

# View coverage report
open coverage/index.html

Test structure:

  • Tests should be in the tests/ directory
  • Each class should have its corresponding test
  • Tests should be descriptive and cover edge cases
  • Use mocks when appropriate
  • Maintain ≥95% coverage — new features must include tests (make test-coverage)

Pull Request Process

  1. Create a branch from main:

    git checkout -b feature/my-new-feature
# or
git checkout -b fix/my-bug-fix

  2. Make your changes:

    • Write clean, well-documented code
    • Add tests for new features
    • Ensure all tests pass
    • Run make qa to verify everything

  3. Commit your changes:

    git add .
git commit -m "feat: description of feature"
# or
git commit -m "fix: description of fix"

    Commit conventions:

    • feat: New feature
    • fix: Bug fix
    • docs: Documentation changes
    • test: Add or modify tests
    • refactor: Code refactoring
    • style: Formatting changes (doesn't affect functionality)
    • chore: Maintenance tasks

  4. Push to your fork:

    git push origin feature/my-new-feature

  5. Create a Pull Request on GitHub:

    • Clearly describe the changes
    • Mention any related issues
    • Add screenshots if relevant
    • Ensure CI passes

Checklist Before PR

  • Code follows PSR-12 standards
  • Ran make cs-fix (or composer cs-fix)
  • All tests pass (make test)
  • Code coverage is ≥95% (make test-coverage)
  • Added tests for new functionality
  • Documentation is updated (if necessary)
  • CHANGELOG.md is updated (if necessary)
  • Code is well commented
  • No warnings or errors from PHPStan/Psalm (if used)

Project Structure

password-toggle-bundle/
├── src/                    # Bundle source code
│   ├── DependencyInjection/ # Bundle configuration
│   ├── Form/               # Form types
│   └── Resources/          # Resources (templates, assets)
├── tests/                  # Tests
├── demo/                   # Demo project
├── .github/                # GitHub configuration
└── docs/                   # Additional documentation (if any)

Demos

The project includes a demo project to test the bundle:

  • demo/ - Demo Symfony project with Docker setup

To run the demo:

# Install dependencies
cd demo
make up
make install

# Start containers
docker-compose up -d

# Access the demo
# http://localhost:8080

Questions

If you have questions about contributing, you can:

Acknowledgments

Thank you for contributing to Password Toggle Bundle. Your help makes this project better for everyone. If CI fails because trailers are already on the remote, see GITHUB_CI.md (REQ-GIT-001) and run make strip-cursor-coauthor-from-history before git push --force-with-lease.