274 lines
9.1 KiB
Markdown
274 lines
9.1 KiB
Markdown
# Contribution Guide
|
|
|
|
* Bug Reports
|
|
* Support Questions
|
|
* Core Development Discussion
|
|
* Which Branch?
|
|
* Compiled Assets
|
|
* Security Vulnerabilities
|
|
* Coding Style
|
|
* PHPDoc
|
|
* StyleCI
|
|
* Code of Conduct
|
|
|
|
## Bug Reports
|
|
|
|
To encourage active collaboration, Laravel strongly encourages pull requests,
|
|
not just bug reports. Pull requests will only be reviewed when marked as
|
|
"ready for review" (not in the "draft" state) and all tests for new features
|
|
are passing. Lingering, non-active pull requests left in the "draft" state
|
|
will be closed after a few days.
|
|
|
|
However, if you file a bug report, your issue should contain a title and a
|
|
clear description of the issue. You should also include as much relevant
|
|
information as possible and a code sample that demonstrates the issue. The
|
|
goal of a bug report is to make it easy for yourself - and others - to
|
|
replicate the bug and develop a fix.
|
|
|
|
Remember, bug reports are created in the hope that others with the same
|
|
problem will be able to collaborate with you on solving it. Do not expect that
|
|
the bug report will automatically see any activity or that others will jump to
|
|
fix it. Creating a bug report serves to help yourself and others start on the
|
|
path of fixing the problem. If you want to chip in, you can help out by fixing
|
|
[any bugs listed in our issue
|
|
trackers](https://github.com/issues?q=is%3Aopen+is%3Aissue+label%3Abug+user%3Alaravel).
|
|
You must be authenticated with GitHub to view all of Laravel's issues.
|
|
|
|
If you notice improper DocBlock, PHPStan, or IDE warnings while using Laravel,
|
|
do not create a GitHub issue. Instead, please submit a pull request to fix the
|
|
problem.
|
|
|
|
The Laravel source code is managed on GitHub, and there are repositories for
|
|
each of the Laravel projects:
|
|
|
|
* [Laravel Application](https://github.com/laravel/laravel)
|
|
* [Laravel Art](https://github.com/laravel/art)
|
|
* [Laravel Documentation](https://github.com/laravel/docs)
|
|
* [Laravel Dusk](https://github.com/laravel/dusk)
|
|
* [Laravel Cashier Stripe](https://github.com/laravel/cashier)
|
|
* [Laravel Cashier Paddle](https://github.com/laravel/cashier-paddle)
|
|
* [Laravel Echo](https://github.com/laravel/echo)
|
|
* [Laravel Envoy](https://github.com/laravel/envoy)
|
|
* [Laravel Folio](https://github.com/laravel/folio)
|
|
* [Laravel Framework](https://github.com/laravel/framework)
|
|
* [Laravel Homestead](https://github.com/laravel/homestead) ([Build Scripts](https://github.com/laravel/settler))
|
|
* [Laravel Horizon](https://github.com/laravel/horizon)
|
|
* [Laravel Livewire Starter Kit](https://github.com/laravel/livewire-starter-kit)
|
|
* [Laravel Passport](https://github.com/laravel/passport)
|
|
* [Laravel Pennant](https://github.com/laravel/pennant)
|
|
* [Laravel Pint](https://github.com/laravel/pint)
|
|
* [Laravel Prompts](https://github.com/laravel/prompts)
|
|
* [Laravel React Starter Kit](https://github.com/laravel/react-starter-kit)
|
|
* [Laravel Reverb](https://github.com/laravel/reverb)
|
|
* [Laravel Sail](https://github.com/laravel/sail)
|
|
* [Laravel Sanctum](https://github.com/laravel/sanctum)
|
|
* [Laravel Scout](https://github.com/laravel/scout)
|
|
* [Laravel Socialite](https://github.com/laravel/socialite)
|
|
* [Laravel Telescope](https://github.com/laravel/telescope)
|
|
* [Laravel Vue Starter Kit](https://github.com/laravel/vue-starter-kit)
|
|
|
|
## Support Questions
|
|
|
|
Laravel's GitHub issue trackers are not intended to provide Laravel help or
|
|
support. Instead, use one of the following channels:
|
|
|
|
* [GitHub Discussions](https://github.com/laravel/framework/discussions)
|
|
* [Laracasts Forums](https://laracasts.com/discuss)
|
|
* [Laravel.io Forums](https://laravel.io/forum)
|
|
* [StackOverflow](https://stackoverflow.com/questions/tagged/laravel)
|
|
* [Discord](https://discord.gg/laravel)
|
|
* [Larachat](https://larachat.co)
|
|
* [IRC](https://web.libera.chat/?nick=artisan&channels=#laravel)
|
|
|
|
## Core Development Discussion
|
|
|
|
You may propose new features or improvements of existing Laravel behavior in
|
|
the Laravel framework repository's [GitHub discussion
|
|
board](https://github.com/laravel/framework/discussions). If you propose a new
|
|
feature, please be willing to implement at least some of the code that would
|
|
be needed to complete the feature.
|
|
|
|
Informal discussion regarding bugs, new features, and implementation of
|
|
existing features takes place in the `#internals` channel of the [Laravel
|
|
Discord server](https://discord.gg/laravel). Taylor Otwell, the maintainer of
|
|
Laravel, is typically present in the channel on weekdays from 8am-5pm
|
|
(UTC-06:00 or America/Chicago), and sporadically present in the channel at
|
|
other times.
|
|
|
|
## Which Branch?
|
|
|
|
**All** bug fixes should be sent to the latest version that supports bug fixes
|
|
(currently `12.x`). Bug fixes should **never** be sent to the `master` branch
|
|
unless they fix features that exist only in the upcoming release.
|
|
|
|
**Minor** features that are **fully backward compatible** with the current
|
|
release may be sent to the latest stable branch (currently `12.x`).
|
|
|
|
**Major** new features or features with breaking changes should always be sent
|
|
to the `master` branch, which contains the upcoming release.
|
|
|
|
## Compiled Assets
|
|
|
|
If you are submitting a change that will affect a compiled file, such as most
|
|
of the files in `resources/css` or `resources/js` of the `laravel/laravel`
|
|
repository, do not commit the compiled files. Due to their large size, they
|
|
cannot realistically be reviewed by a maintainer. This could be exploited as a
|
|
way to inject malicious code into Laravel. In order to defensively prevent
|
|
this, all compiled files will be generated and committed by Laravel
|
|
maintainers.
|
|
|
|
## Security Vulnerabilities
|
|
|
|
If you discover a security vulnerability within Laravel, please send an email
|
|
to Taylor Otwell at [](/cdn-cgi/l/email-
|
|
protection#b3c7d2cadfdcc1f3dfd2c1d2c5d6df9dd0dcde)[[email protected]](/cdn-
|
|
cgi/l/email-protection#8efaeff7e2e1fccee2effceff8ebe2a0ede1e3). All security
|
|
vulnerabilities will be promptly addressed.
|
|
|
|
## Coding Style
|
|
|
|
Laravel follows the [PSR-2](https://github.com/php-fig/fig-
|
|
standards/blob/master/accepted/PSR-2-coding-style-guide.md) coding standard
|
|
and the [PSR-4](https://github.com/php-fig/fig-
|
|
standards/blob/master/accepted/PSR-4-autoloader.md) autoloading standard.
|
|
|
|
### PHPDoc
|
|
|
|
Below is an example of a valid Laravel documentation block. Note that the
|
|
`@param` attribute is followed by two spaces, the argument type, two more
|
|
spaces, and finally the variable name:
|
|
|
|
|
|
|
|
1/**
|
|
|
|
2 * Register a binding with the container.
|
|
|
|
3 *
|
|
|
|
4 * @param string|array $abstract
|
|
|
|
5 * @param \Closure|string|null $concrete
|
|
|
|
6 * @param bool $shared
|
|
|
|
7 * @return void
|
|
|
|
8 *
|
|
|
|
9 * @throws \Exception
|
|
|
|
10 */
|
|
|
|
11public function bind($abstract, $concrete = null, $shared = false)
|
|
|
|
12{
|
|
|
|
13 // ...
|
|
|
|
14}
|
|
|
|
|
|
/**
|
|
* Register a binding with the container.
|
|
*
|
|
* @param string|array $abstract
|
|
* @param \Closure|string|null $concrete
|
|
* @param bool $shared
|
|
* @return void
|
|
*
|
|
* @throws \Exception
|
|
*/
|
|
public function bind($abstract, $concrete = null, $shared = false)
|
|
{
|
|
// ...
|
|
}
|
|
|
|
When the `@param` or `@return` attributes are redundant due to the use of
|
|
native types, they can be removed:
|
|
|
|
|
|
|
|
1/**
|
|
|
|
2 * Execute the job.
|
|
|
|
3 */
|
|
|
|
4public function handle(AudioProcessor $processor): void
|
|
|
|
5{
|
|
|
|
6 //
|
|
|
|
7}
|
|
|
|
|
|
/**
|
|
* Execute the job.
|
|
*/
|
|
public function handle(AudioProcessor $processor): void
|
|
{
|
|
//
|
|
}
|
|
|
|
However, when the native type is generic, please specify the generic type
|
|
through the use of the `@param` or `@return` attributes:
|
|
|
|
|
|
|
|
1/**
|
|
|
|
2 * Get the attachments for the message.
|
|
|
|
3 *
|
|
|
|
4 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
|
|
|
|
5 */
|
|
|
|
6public function attachments(): array
|
|
|
|
7{
|
|
|
|
8 return [
|
|
|
|
9 Attachment::fromStorage('/path/to/file'),
|
|
|
|
10 ];
|
|
|
|
11}
|
|
|
|
|
|
/**
|
|
* Get the attachments for the message.
|
|
*
|
|
* @return array<int, \Illuminate\Mail\Mailables\Attachment>
|
|
*/
|
|
public function attachments(): array
|
|
{
|
|
return [
|
|
Attachment::fromStorage('/path/to/file'),
|
|
];
|
|
}
|
|
|
|
### StyleCI
|
|
|
|
Don't worry if your code styling isn't perfect! [StyleCI](https://styleci.io/)
|
|
will automatically merge any style fixes into the Laravel repository after
|
|
pull requests are merged. This allows us to focus on the content of the
|
|
contribution and not the code style.
|
|
|
|
## Code of Conduct
|
|
|
|
The Laravel code of conduct is derived from the Ruby code of conduct. Any
|
|
violations of the code of conduct may be reported to Taylor Otwell ([[email
|
|
protected]](/cdn-cgi/l/email-
|
|
protection#b0c4d1c9dcdfc2f0dcd1c2d1c6d5dc9ed3dfdd)):
|
|
|
|
* Participants will be tolerant of opposing views.
|
|
* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
|
|
* When interpreting the words and actions of others, participants should always assume good intentions.
|
|
* Behavior that can be reasonably considered harassment will not be tolerated.
|
|
|