Contributing Guide

Thank you for considering contributing to Mono CLI! This document outlines the process and guidelines for contributing.

Code of Conduct

Be respectful, inclusive, and professional in all interactions.

Getting Started

Fork the repository
Clone your fork: git clone https://github.com/your-username/mono-php.git
Create a feature branch: git checkout -b feature/your-feature-name
Install dependencies: cd cli && composer install

Development Workflow

Before Making Changes

Ensure all tests pass: composer test
Check code quality: composer check

Making Changes

Write clean, well-documented code
Follow PSR-12 coding standards
Add comprehensive docblocks to all classes and methods
Write unit tests for new functionality
Update documentation as needed

Code Style

We use Laravel Pint for code formatting:

# Check code style
composer lint

# Fix code style automatically
composer format

Static Analysis

We use PHPStan at level 8 for static analysis:

# Run static analysis
composer typecheck

Refactoring

We use Rector for automated refactoring:

# Preview refactoring changes
composer refactor:dry

# Apply refactoring
composer refactor

Testing

Write comprehensive tests for all new features:

# Run all tests
composer test

# Run tests with coverage
composer test:coverage

Test requirements:

Unit tests for all new classes and methods
Feature tests for command workflows
Minimum 80% code coverage for new code
All tests must pass before submitting PR

Quality Checks

Run all quality checks before committing:

# Run all checks (test, lint, typecheck, refactor)
composer check

# Fix all auto-fixable issues
composer fix

Commit Guidelines

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples

feat(commands): add workspace initialization command

Add new make:workspace command that creates a new monorepo workspace
with interactive prompts for name and type selection.

Closes #123

fix(composer): handle missing composer.json gracefully

Check if composer.json exists before attempting to parse it.
Display helpful error message when file is missing.

Pull Request Process

Update documentation for any changed functionality
Add tests for new features
Ensure all quality checks pass: composer check
Update CHANGELOG.md with your changes
Submit PR with clear description of changes
Link related issues in PR description
Wait for code review and address feedback

PR Title Format

Use the same format as commit messages:

feat(commands): add workspace initialization command

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests added/updated
- [ ] Feature tests added/updated
- [ ] All tests passing
- [ ] Manual testing completed

## Checklist
- [ ] Code follows PSR-12 standards
- [ ] Docblocks added/updated
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] All quality checks pass

Project Structure

cli/
├── bin/                  # Executable scripts
├── src/
│   ├── Application.php   # Main application class
│   ├── Commands/         # Command classes
│   │   ├── BaseCommand.php
│   │   ├── Composer/     # Composer integration
│   │   ├── Deploy/       # Deployment commands
│   │   ├── Dev/          # Development commands
│   │   ├── Lifecycle/    # Installation & cleanup
│   │   ├── Make/         # Scaffolding commands
│   │   ├── Quality/      # Testing & quality
│   │   ├── Turbo/        # Turborepo commands
│   │   ├── Utility/      # Utility commands
│   │   └── Workspace/    # Workspace management
│   ├── Concerns/         # Reusable traits
│   └── Support/          # Helper classes
├── tests/
│   ├── Unit/             # Unit tests
│   ├── Feature/          # Feature tests
│   ├── Fixtures/         # Test fixtures
│   └── TestCase.php      # Base test case
├── build/                # Build artifacts (gitignored)
└── vendor/               # Dependencies (gitignored)

Adding New Commands

Create command class in appropriate directory under src/Commands/
Extend BaseCommand class
Implement configure() and execute() methods
Add comprehensive docblocks
Call parent::configure() to inherit common options
Register command in Application.php if not auto-discovered
Write unit tests in tests/Unit/Commands/
Write feature tests in tests/Feature/
Update documentation

Command Template

<?php

declare(strict_types=1);

namespace MonoPhp\Cli\Console\Commands\Category;

use MonoPhp\Cli\Console\Commands\BaseCommand;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

/**
 * Brief description of what the command does.
 *
 * Detailed explanation of the command's purpose and behavior.
 *
 * @package MonoPhp\Cli\Console\Commands\Category
 */
class YourCommand extends BaseCommand
{
    /**
     * Configure the command.
     *
     * Sets up command name, description, arguments, and options.
     * Inherits common options from BaseCommand (--workspace, --force, etc.).
     */
    protected function configure(): void
    {
        parent::configure();

        $this
            ->setName('your:command')
            ->setDescription('Brief description')
            ->setHelp('Detailed help text');
    }

    /**
     * Execute the command.
     *
     * @param InputInterface  $input  Command input
     * @param OutputInterface $output Command output
     *
     * @return int Exit code (0 for success, non-zero for failure)
     */
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        // Implementation here

        return self::SUCCESS;
    }
}

Documentation

Update README.md for user-facing changes
Update inline code documentation (docblocks)
Add examples for new features
Update CHANGELOG.md

Questions?

Open an issue for bugs or feature requests
Start a discussion for questions or ideas
Check existing issues before creating new ones

License

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

PreviousEnvironment Variables NextDevelopment Setup

Last updated 1 month ago

hashtagCode of Conduct

hashtagGetting Started

hashtagDevelopment Workflow

hashtagBefore Making Changes

hashtagMaking Changes

hashtagCode Style

hashtagStatic Analysis

hashtagRefactoring

hashtagTesting

hashtagQuality Checks

hashtagCommit Guidelines

hashtagCommit Message Format

hashtagTypes

hashtagExamples

hashtagPull Request Process

hashtagPR Title Format

hashtagPR Description Template

hashtagProject Structure

hashtagAdding New Commands

hashtagCommand Template

hashtagDocumentation

hashtagQuestions?

hashtagLicense