기여 가이드 (Contribution Guide)

• 버그 보고
• 지원 질문
• 코어 개발 논의
• 어느 브랜치?
• 컴파일된 에셋
• 보안 취약점
• 코딩 스타일
  • PHPDoc
  • StyleCI
• 행동 강령

버그 보고 (Bug Reports)

활발한 협업을 장려하기 위해, Laravel은 단순한 버그 보고보다 pull request를 강력히 권장합니다. Pull request는 "ready for review"로 표시되어 있고("draft" 상태가 아니며), 새 기능에 대한 모든 테스트가 통과하는 경우에만 검토됩니다. "draft" 상태로 오래 남아 있고 활동이 없는 pull request는 며칠 후 닫힙니다.

하지만 버그 보고를 작성한다면, 해당 이슈에는 제목과 문제에 대한 명확한 설명이 포함되어야 합니다. 또한 가능한 한 많은 관련 정보와 문제를 보여 주는 코드 예제를 함께 포함해야 합니다. 버그 보고의 목표는 자신과 다른 사람들이 버그를 쉽게 재현하고 수정 방법을 개발할 수 있게 하는 것입니다.

버그 보고는 같은 문제를 겪는 다른 사람들이 여러분과 함께 문제 해결에 협력할 수 있기를 기대하며 작성된다는 점을 기억하세요. 버그 보고를 만들었다고 해서 자동으로 어떤 활동이 일어나거나, 다른 사람이 곧바로 수정에 나설 것이라고 기대해서는 안 됩니다. 버그 보고는 자신과 다른 사람들이 문제를 해결하기 위한 첫걸음을 시작하도록 돕는 역할을 합니다. 직접 기여하고 싶다면 이슈 트래커에 등록된 버그를 수정하여 도울 수 있습니다. Laravel의 모든 이슈를 보려면 GitHub에 인증되어 있어야 합니다.

Laravel을 사용하는 동안 부적절한 DocBlock, PHPStan, 또는 IDE 경고를 발견했다면 GitHub 이슈를 만들지 마세요. 대신 문제를 수정하는 pull request를 제출해 주세요.

Laravel 소스 코드는 GitHub에서 관리되며, 각 Laravel 프로젝트별로 저장소가 있습니다.

• Laravel Application
• Laravel Art
• Laravel Boost
• Laravel Documentation
• Laravel Dusk
• Laravel Cashier Stripe
• Laravel Cashier Paddle
• Laravel Echo
• Laravel Envoy
• Laravel Folio
• Laravel Framework
• Laravel Horizon
• Laravel Passport
• Laravel Pennant
• Laravel Pint
• Laravel Prompts
• Laravel Reverb
• Laravel Sail
• Laravel Sanctum
• Laravel Scout
• Laravel Socialite
• Laravel Telescope
• Laravel Livewire Starter Kit
• Laravel React Starter Kit
• Laravel Svelte Starter Kit
• Laravel Vue Starter Kit

지원 질문 (Support Questions)

Laravel의 GitHub 이슈 트래커는 Laravel 도움말이나 지원을 제공하기 위한 곳이 아닙니다. 대신 다음 채널 중 하나를 사용하세요.

• GitHub Discussions
• Laracasts Forums
• Laravel.io Forums
• StackOverflow
• Discord
• Larachat
• IRC

코어 개발 논의 (Core Development Discussion)

Laravel framework 저장소의 GitHub discussion board에서 새 기능이나 기존 Laravel 동작의 개선을 제안할 수 있습니다. 새 기능을 제안한다면, 해당 기능을 완성하는 데 필요한 코드 중 적어도 일부를 직접 구현할 의향이 있어야 합니다.

버그, 새 기능, 기존 기능 구현에 관한 비공식 논의는 Laravel Discord server의 #internals 채널에서 이루어집니다. Laravel의 메인테이너인 Taylor Otwell은 보통 평일 오전 8시부터 오후 5시까지(UTC-06:00 또는 America/Chicago) 해당 채널에 있으며, 그 외 시간에도 간헐적으로 참여합니다.

어느 브랜치? (Which Branch?)

모든 버그 수정은 버그 수정을 지원하는 최신 버전(현재 12.x)으로 보내야 합니다. 다가오는 릴리스에만 존재하는 기능을 수정하는 경우가 아니라면, 버그 수정은 절대로 master 브랜치로 보내서는 안 됩니다.

현재 릴리스와 완전히 하위 호환되는 마이너 기능은 최신 안정 브랜치(현재 12.x)로 보낼 수 있습니다.

메이저 새 기능이나 breaking changes가 포함된 기능은 항상 다가오는 릴리스를 포함하는 master 브랜치로 보내야 합니다.

컴파일된 에셋 (Compiled Assets)

laravel/laravel 저장소의 resources/css 또는 resources/js에 있는 대부분의 파일처럼 컴파일된 파일에 영향을 주는 변경 사항을 제출하는 경우, 컴파일된 파일을 커밋하지 마세요. 이러한 파일은 크기가 크기 때문에 메인테이너가 현실적으로 검토하기 어렵습니다. 이는 Laravel에 악성 코드를 주입하는 방식으로 악용될 수 있습니다. 이를 방어적으로 방지하기 위해, 모든 컴파일된 파일은 Laravel 메인테이너가 생성하고 커밋합니다.

보안 취약점 (Security Vulnerabilities)

Laravel 내에서 보안 취약점을 발견했다면 Taylor Otwell에게 [email protected]으로 이메일을 보내 주세요. 모든 보안 취약점은 신속하게 처리됩니다.

코딩 스타일 (Coding Style)

Laravel은 PSR-2 코딩 표준과 PSR-4 오토로딩 표준을 따릅니다.

PHPDoc

아래는 올바른 Laravel 문서 블록의 예시입니다. @param 속성 뒤에는 공백 두 칸, 인수 타입, 다시 공백 두 칸, 마지막으로 변수명이 온다는 점에 유의하세요.

/**
 * 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)
{
    // ...
}

네이티브 타입을 사용하기 때문에 @param 또는 @return 속성이 중복된다면 제거할 수 있습니다.

/**
 * Execute the job.
 */
public function handle(AudioProcessor $processor): void
{
    // ...
}

하지만 네이티브 타입이 제네릭이라면 @param 또는 @return 속성을 사용해 제네릭 타입을 지정해 주세요.

/**
 * Get the attachments for the message.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromStorage('/path/to/file'),
    ];
}

StyleCI

코드 스타일이 완벽하지 않아도 걱정하지 마세요. Pull request가 병합된 후 StyleCI가 모든 스타일 수정 사항을 Laravel 저장소에 자동으로 병합합니다. 덕분에 우리는 코드 스타일이 아니라 기여 내용 자체에 집중할 수 있습니다.

행동 강령 (Code of Conduct)

Laravel 행동 강령은 Ruby 행동 강령을 바탕으로 합니다. 행동 강령 위반 사항은 Taylor Otwell([email protected])에게 신고할 수 있습니다.

• 참가자는 반대 의견에 관대해야 합니다.
• 참가자는 자신의 언어와 행동에 개인 공격이나 비하성 개인 발언이 포함되지 않도록 해야 합니다.
• 다른 사람의 말과 행동을 해석할 때 참가자는 항상 좋은 의도를 전제로 해야 합니다.
• 합리적으로 괴롭힘으로 간주될 수 있는 행동은 허용되지 않습니다.