|
| 1 | +# Contributing to laravel-setanjo |
| 2 | + |
| 3 | +Thank you for considering contributing to laravel-setanjo! This document provides guidelines and information for contributors. |
| 4 | + |
| 5 | +## Code of Conduct |
| 6 | + |
| 7 | +This project adheres to a code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers. |
| 8 | + |
| 9 | +## How Can I Contribute? |
| 10 | + |
| 11 | +### Reporting Bugs |
| 12 | + |
| 13 | +Before creating bug reports, please check the existing issues to avoid duplicates. When creating a bug report, include: |
| 14 | + |
| 15 | +- **Clear title and description** |
| 16 | +- **Steps to reproduce** the issue |
| 17 | +- **Expected vs actual behavior** |
| 18 | +- **Environment details** (PHP version, Laravel version, package version) |
| 19 | +- **Code samples** that demonstrate the issue |
| 20 | + |
| 21 | +### Suggesting Enhancements |
| 22 | + |
| 23 | +Enhancement suggestions are welcome! Please provide: |
| 24 | + |
| 25 | +- **Clear title and detailed description** |
| 26 | +- **Use case** explaining why this enhancement would be useful |
| 27 | +- **Possible implementation** details if you have ideas |
| 28 | + |
| 29 | +### Pull Requests |
| 30 | + |
| 31 | +1. **Fork** the repository |
| 32 | +2. **Create a feature branch** from `main` |
| 33 | +3. **Make your changes** following our coding standards |
| 34 | +4. **Add tests** for new functionality |
| 35 | +5. **Ensure all tests pass** |
| 36 | +6. **Update documentation** if needed |
| 37 | +7. **Submit a pull request** |
| 38 | + |
| 39 | +## Development Setup |
| 40 | + |
| 41 | +```bash |
| 42 | +# Clone your fork |
| 43 | +git clone https://github.com/ahs12/laravel-setanjo.git |
| 44 | +cd laravel-setanjo |
| 45 | + |
| 46 | +# Install dependencies |
| 47 | +composer install |
| 48 | + |
| 49 | +# Run tests |
| 50 | +composer test |
| 51 | + |
| 52 | +# Run code style fixes |
| 53 | +composer format |
| 54 | +``` |
| 55 | + |
| 56 | +## Coding Standards |
| 57 | + |
| 58 | +- Follow **PSR-12** coding standards |
| 59 | +- Use **meaningful variable and method names** |
| 60 | +- Add **type hints** where possible |
| 61 | +- Write **comprehensive tests** for new features |
| 62 | +- Keep **backward compatibility** in mind |
| 63 | + |
| 64 | +### Code Style |
| 65 | + |
| 66 | +We use Pint Fixer to maintain consistent code style: |
| 67 | + |
| 68 | +```bash |
| 69 | +# Check code style |
| 70 | +composer format |
| 71 | + |
| 72 | +``` |
| 73 | + |
| 74 | +## Testing |
| 75 | + |
| 76 | +All contributions must include appropriate tests: |
| 77 | + |
| 78 | +```bash |
| 79 | +# Run all tests |
| 80 | +composer test |
| 81 | + |
| 82 | +# Run tests with coverage |
| 83 | +composer test-coverage |
| 84 | + |
| 85 | +# Run specific test file |
| 86 | +./vendor/bin/pest tests/Unit/SettingsTest.php |
| 87 | +``` |
| 88 | + |
| 89 | +### Writing Tests |
| 90 | + |
| 91 | +- Use **Pest PHP** for testing |
| 92 | +- Test both **happy path and edge cases** |
| 93 | +- Include tests for **multi-tenant scenarios** |
| 94 | +- Mock external dependencies when appropriate |
| 95 | + |
| 96 | +Example test structure: |
| 97 | +```php |
| 98 | +it('can set and get global settings', function () { |
| 99 | + Settings::set('test_key', 'test_value'); |
| 100 | + |
| 101 | + expect(Settings::get('test_key'))->toBe('test_value'); |
| 102 | +}); |
| 103 | + |
| 104 | +it('can set tenant-specific settings', function () { |
| 105 | + $user = User::factory()->create(); |
| 106 | + |
| 107 | + Settings::for($user)->set('theme', 'dark'); |
| 108 | + |
| 109 | + expect(Settings::for($user)->get('theme'))->toBe('dark'); |
| 110 | +}); |
| 111 | +``` |
| 112 | + |
| 113 | +## Documentation |
| 114 | + |
| 115 | +- Update **README.md** for new features |
| 116 | +- Add **inline documentation** for complex methods |
| 117 | +- Include **usage examples** in docblocks |
| 118 | +- Update **configuration examples** when needed |
| 119 | + |
| 120 | +## Commit Messages |
| 121 | + |
| 122 | +Use clear, descriptive commit messages: |
| 123 | + |
| 124 | +``` |
| 125 | +feat: add support for custom cache stores |
| 126 | +fix: resolve tenant isolation issue |
| 127 | +docs: update installation instructions |
| 128 | +test: add tests for polymorphic settings |
| 129 | +refactor: improve type casting performance |
| 130 | +``` |
| 131 | + |
| 132 | +Prefix types: |
| 133 | +- `feat:` New features |
| 134 | +- `fix:` Bug fixes |
| 135 | +- `docs:` Documentation changes |
| 136 | +- `test:` Test additions/changes |
| 137 | +- `refactor:` Code refactoring |
| 138 | +- `style:` Code style changes |
| 139 | +- `chore:` Maintenance tasks |
| 140 | + |
| 141 | +## Review Process |
| 142 | + |
| 143 | +1. **Automated checks** must pass (tests, code style) |
| 144 | +2. **Manual review** by maintainers |
| 145 | +3. **Discussion** if changes are needed |
| 146 | +4. **Approval** and merge |
| 147 | + |
| 148 | +## Release Process |
| 149 | + |
| 150 | +Releases follow [Semantic Versioning](https://semver.org/): |
| 151 | + |
| 152 | +- **MAJOR**: Breaking changes |
| 153 | +- **MINOR**: New features (backward compatible) |
| 154 | +- **PATCH**: Bug fixes (backward compatible) |
| 155 | + |
| 156 | +## Getting Help |
| 157 | + |
| 158 | +- **GitHub Issues**: For bugs and feature requests |
| 159 | +- **GitHub Discussions**: For questions and general discussion |
| 160 | +- **Email**: Contact maintainers directly for sensitive issues |
| 161 | + |
| 162 | +## Recognition |
| 163 | + |
| 164 | +Contributors will be acknowledged in: |
| 165 | +- **CHANGELOG.md** for their contributions |
| 166 | +- **README.md** contributors section |
| 167 | +- **GitHub contributors** page |
| 168 | + |
| 169 | +Thank you for helping make laravel-setanjo better! 🚀 |
0 commit comments