Skip to main content

​
We Welcome Contributions

Thank you for considering contributing to Laravel Permission! This package is open source and we love to receive contributions from the community.

​
Ways to Contribute

There are many ways to contribute to this project:

Report Bugs

Found a bug? Let us know by creating an issue on GitHub.

Suggest Features

Have an idea for improvement? We’d love to hear it.

Improve Documentation

Help make the docs better for everyone.

Submit Code

Fix bugs or implement new features with pull requests.

​
Reporting Issues

​
Before Creating an Issue

1

Search existing issues

Check if your issue has already been reported in the GitHub Issues.
2

Check the documentation

Review the documentation and troubleshooting guide to see if your question is already answered.
3

Try the latest version

Ensure you’re using the latest version of the package, as your issue may already be fixed.

​
Creating a Good Issue Report

When creating an issue, please include: 
**Environment:**
- Package version: (e.g., 7.2.3)
- Laravel version: (e.g., 12.0)
- PHP version: (e.g., 8.4)
- Database: (e.g., MySQL 8.0)

**Description:**
Clear description of the issue

**Steps to Reproduce:**
1. Step one
2. Step two
3. ...

**Expected Behavior:**
What you expected to happen

**Actual Behavior:**
What actually happened

**Code Samples:**
[Include relevant code snippets]

**Error Messages:**
[Include complete error messages and stack traces]
Security Issues: If you discover a security vulnerability, please email [email protected] instead of creating a public issue.

​
Contributing Code

​
Development Setup

1

Fork the repository

Fork the laravel-permission repository to your GitHub account.
2

Clone your fork

git clone https://github.com/YOUR-USERNAME/laravel-permission.git
cd laravel-permission
3

Install dependencies

composer install
4

Create a branch

Create a new branch for your changes:
git checkout -b feature/your-feature-name
Or for bug fixes:
git checkout -b fix/issue-description

​
Coding Standards

This package follows the PSR-12 coding standard and uses Laravel Pint for code formatting. Before committing, format your code: 
./vendor/bin/pint
Code that doesn’t follow the style guidelines will not be accepted.

​
Writing Tests

All new features and bug fixes must include tests. This package uses Pest for testing. Run the test suite: 
composer test
Run specific tests: 
./vendor/bin/pest --filter="test name"
Test Coverage: Aim for high test coverage for your changes: 
composer test-coverage

test('users can be assigned roles', function () {
    $role = Role::create(['name' => 'writer']);
    $user = User::factory()->create();
    
    $user->assignRole($role);
    
    expect($user->hasRole('writer'))->toBeTrue();
    expect($user->roles)->toHaveCount(1);
});

test('assigning non-existent role throws exception', function () {
    $user = User::factory()->create();
    
    $user->assignRole('non-existent');
})->throws(RoleDoesNotExist::class);

​
Submitting a Pull Request

1

Ensure tests pass

composer test
./vendor/bin/pint
2

Commit your changes

Write clear, descriptive commit messages:
git add .
git commit -m "Add feature: description of feature"
Follow conventional commit format when possible:
  • feat: for new features
  • fix: for bug fixes
  • docs: for documentation changes
  • test: for test additions/changes
  • refactor: for code refactoring
3

Push to your fork

git push origin feature/your-feature-name
4

Create pull request

Go to the original repository and create a pull request from your fork.Include in your PR description:
  • What changes you made
  • Why you made them
  • Any relevant issue numbers (e.g., “Fixes #123”)
  • Screenshots if applicable (for UI changes)

​
Pull Request Guidelines

  • Ensure your code follows PSR-12 standards
  • Run ./vendor/bin/pint to format code
  • All tests must pass
  • Add tests for new functionality
  • Update documentation if needed
  • Keep pull requests focused on a single concern
  • Rebase your branch if needed to keep history clean
  1. Automated checks will run (tests, code style)
  2. Maintainers will review your code
  3. Address feedback if requested
  4. Merge once approved
Maintainers may request changes or provide suggestions. This is normal and helps maintain code quality.

​
Improving Documentation

Documentation improvements are always welcome!

​
Documentation Location

The documentation source files are in the /docs directory of the repository.

​
Documentation Guidelines

  • Use clear, simple language
  • Include code examples
  • Test all code examples
  • Add navigation entries if creating new pages
  • Use proper markdown formatting
  • Include relevant links to related topics
To suggest documentation changes:
  1. Edit the markdown files in /docs
  2. Submit a pull request
  3. Tag it with the documentation label

​
Community Guidelines

When participating in discussions:
  • Be respectful and constructive
  • Stay on topic
  • Help others when you can
  • Follow the Code of Conduct

​
Recognition

Contributors are recognized in:

​
Development Resources

GitHub Repository

View source code and contribute

Issue Tracker

Report bugs or request features

Pull Requests

View open pull requests

Discussions

Ask questions and share ideas

​
Questions?

If you have questions about contributing:
  1. Check the documentation
  2. Search existing issues
  3. Start a discussion
  4. Ask in the Spatie Discord

​
Support Spatie

Spatie invests significant resources in creating and maintaining open source packages. You can support their work by:
All postcards received are published on Spatie’s virtual postcard wall.

​
License

By contributing, you agree that your contributions will be licensed under the MIT License.
Thank you for contributing to Laravel Permission! Your efforts help make this package better for everyone.

Build docs developers (and LLMs) love

Get started for freeTalk to us