Skip to main content

풀 리퀘스트

로컬 환경 설정​

1단계: 포크​

GitHub에서 프로젝트를 포크하고, 포크한 저장소를 로컬에 클론한다.

$ git clone git@github.com:username/electron.git
$ cd electron
$ git remote add upstream https://github.com/electron/electron.git
$ git fetch upstream

Step 2: 프로젝트 빌드​

빌드 단계와 필요한 의존성은 운영체제에 따라 약간씩 다르다. 로컬에서 Electron을 빌드하는 자세한 가이드는 아래 링크를 참고한다:

로컬에서 프로젝트를 빌드한 후에는 변경 작업을 시작할 준비가 된 것이다!

Step 3: 브랜치 생성​

개발 환경을 체계적으로 유지하려면 작업을 담을 로컬 브랜치를 만든다. 이 브랜치는 main 브랜치에서 직접 분기해야 한다.

$ git checkout -b my-branch -t upstream/main

변경 사항 적용하기​

4단계: 코드 수정​

electron/electron 저장소에 대한 대부분의 풀 리퀘스트는 shell/ 폴더 내의 C/C++ 코드, lib/ 폴더 내의 자바스크립트 코드, docs/api/ 내의 문서, 또는 spec/ 폴더 내의 테스트 중 하나를 변경한다.

코드를 수정할 때는 프로젝트의 코드 스타일을 준수하는지 확인하기 위해 수시로 npm run lint를 실행해야 한다.

프로젝트의 다양한 부분에서 코드를 수정할 때의 모범 사례에 대한 자세한 내용은 코딩 스타일 문서를 참고한다.

5단계: 커밋​

변경 사항을 논리적으로 그룹화하여 개별 커밋에 포함하는 것을 권장한다. 여러 커밋으로 나뉜 변경 사항은 리뷰가 더 쉬워진다. 풀 리퀘스트 내에서 커밋 수에는 제한이 없다.

$ git add my/changed/files
$ git commit

여러 커밋은 병합될 때 하나로 합쳐진다는 점을 유의한다.

커밋 메시지 작성 가이드​

좋은 커밋 메시지는 무엇이 변경되었고 왜 변경되었는지를 명확히 설명해야 한다. Electron 프로젝트는 릴리스 프로세스를 간소화하기 위해 시맨틱 커밋 메시지를 사용한다.

풀 리퀘스트가 병합되기 전에, 반드시 시맨틱 접두사가 포함된 풀 리퀘스트 제목이 있어야 한다.

시맨틱 접두사가 포함된 커밋 메시지 예시:

  • fix: prevent_default가 기본적으로 방지되지 않았을 때 덮어쓰지 않도록 수정
  • feat: app.isPackaged() 메서드 추가
  • docs: app.isDefaultProtocolClient가 이제 Linux에서 사용 가능함을 문서화

일반적으로 사용되는 접두사:

  • fix: 버그 수정
  • feat: 새로운 기능 추가
  • docs: 문서 변경
  • test: 누락된 테스트 추가 또는 기존 테스트 수정
  • build: 빌드 시스템에 영향을 미치는 변경
  • ci: CI 설정 파일 및 스크립트 변경
  • perf: 성능을 향상시키는 코드 변경
  • refactor: 버그 수정이나 기능 추가가 아닌 코드 변경
  • style: 코드 의미에 영향을 주지 않는 변경 (린팅)

커밋 메시지를 작성할 때 유의할 사항:

  1. 첫 번째 줄은:
    • 변경 사항에 대한 간단한 설명을 포함한다 (가능하면 50자 이내, 최대 72자).
    • 고유 명사, 약어, 함수/변수명 같은 코드를 참조하는 단어를 제외하고 모두 소문자로 작성한다.
  2. 두 번째 줄은 비워둔다.
  3. 나머지 줄은 72자에서 줄바꿈한다.

주요 변경 사항​

커밋 메시지의 옵션인 본문 또는 푸터 섹션의 시작 부분에 BREAKING CHANGE: 텍스트가 포함되면, 이는 주요 API 변경을 의미한다. 이는 시맨틱 버전 관리에서 Major 버전 변경에 해당한다. 주요 변경 사항은 모든 타입의 커밋에 포함될 수 있다. 예를 들어 fix:, feat:, chore: 등의 타입뿐만 아니라 다른 모든 타입에도 적용 가능하다.

자세한 내용은 conventionalcommits.org를 참고한다.

6단계: 리베이스 실행​

변경 사항을 커밋한 후에는 git merge 대신 git rebase를 사용해 메인 리포지토리와 작업을 동기화하는 것이 좋다.

$ git fetch upstream
$ git rebase upstream/main

이 명령어를 실행하면 작업 중인 브랜치가 electron/electron 메인의 최신 변경 사항을 반영하게 된다.

Step 7: 테스트​

버그 수정과 새로운 기능은 항상 테스트와 함께 제공해야 한다. 테스트 과정을 더 쉽게 하기 위해 테스트 가이드를 참고할 수 있다. 다른 테스트를 살펴보고 구조를 파악하는 것도 도움이 된다.

변경 사항을 풀 리퀘스트로 제출하기 전에 항전체 테스트 스위트를 실행해야 한다. 테스트를 실행하려면 다음 명령어를 사용한다:

$ npm run test

린터가 문제를 보고하지 않고 모든 테스트가 통과하는지 확인한다. 두 가지 검사 중 하나라도 실패하면 패치를 제출하지 않는다.

테스트를 업데이트하고 특정 스펙만 실행해 확인하고 싶다면 다음 명령어를 사용한다:

$ npm run test -match=menu

위 명령어는 menu와 일치하는 스펙 모듈만 실행한다. 이는 테스트 주기의 마지막에 위치할 수 있는 테스트를 작업할 때 유용하다.

Step 8: 변경 사항 푸시​

테스트와 린트 검사를 모두 통과한 커밋이 준비되면, 작업 브랜치를 GitHub 포크에 푸시하여 풀 리퀘스트를 시작한다.

$ git push origin my-branch

9단계: Pull Request 열기​

GitHub 내에서 새로운 Pull Request를 열면 작성해야 할 템플릿이 표시된다. 이 템플릿은 여기에서 확인할 수 있다.

이 템플릿을 충분히 작성하지 않으면, 유지 관리자가 추가 정보를 요청하거나 모호한 부분을 명확히 해야 할 수 있어 PR이 병합되기까지 지연될 수 있다.

10단계: 논의 및 업데이트​

여러분의 풀 리퀘스트에 대한 피드백이나 변경 요청이 들어올 가능성이 높다. 이는 제출 과정의 중요한 부분이므로 낙담하지 말자! 일부 기여자는 즉시 풀 리퀘스트에 승인을 할 수도 있다. 다른 기여자는 자세한 코멘트나 피드백을 제공할 수도 있다. 이는 변경 사항이 올바르고 필요한지 평가하기 위한 필수적인 과정이다.

기존 풀 리퀘스트에 변경 사항을 적용하려면, 로컬 브랜치에서 변경을 수행하고, 그 변경 사항을 새로운 커밋으로 추가한 다음, 해당 변경 사항을 포크에 푸시한다. GitHub는 자동으로 풀 리퀘스트를 업데이트한다.

$ git add my/changed/files
$ git commit
$ git push origin my-branch

git rebase를 사용하여 커밋을 관리하는 더 고급 메커니즘이 있지만, 이 가이드의 범위를 벗어난다.

리뷰어의 답변을 기다리고 있다면 풀 리퀘스트에 코멘트를 남겨 리뷰어에게 알리는 것도 좋다. 익숙하지 않은 단어나 약어를 만나면 이 용어집을 참고하자.

승인 및 변경 요청 워크플로​

모든 풀 리퀘스트는 수정한 영역의 코드 소유자로부터 승인을 받아야만 머지할 수 있다. 메인테이너가 풀 리퀘스트를 리뷰할 때 변경을 요청할 수 있다. 이는 오타 수정과 같은 사소한 것일 수도 있고, 실질적인 변경이 필요한 경우일 수도 있다. 이러한 요청은 도움을 주기 위한 것이지만, 때로는 갑작스럽거나 도움이 되지 않게 느껴질 수 있다. 특히 어떻게 변경해야 하는지에 대한 구체적인 제안이 포함되지 않은 경우 더욱 그렇다.

너무 낙담하지 말자. 리뷰가 불공평하다고 생각되면 그렇게 말하거나 다른 프로젝트 기여자의 의견을 구해보자. 종종 이러한 코멘트는 리뷰어가 충분한 시간을 들이지 않고 리뷰한 결과일 뿐, 악의적인 의도는 아니다. 이런 어려움은 약간의 인내심으로 해결할 수 있는 경우가 많다. 그렇지만 리뷰어는 도움이 되는 피드백을 제공해야 한다는 점은 명심해야 한다.

11단계: 코드 병합​

코드를 병합하려면 최소 한 명의 Electron 코드 소유자로부터 리뷰와 승인이 필요하며, CI(지속적 통합) 테스트를 통과해야 한다. 이후 다른 기여자로부터 이의 제기가 없다면, 풀 리퀘스트를 병합할 수 있다.

기여해 주셔서 감사합니다! 축하드립니다!

지속적 통합 테스트​

모든 풀 리퀘스트는 지속적 통합(CI) 시스템에서 테스트를 거쳐 Electron이 지원하는 플랫폼에서 정상적으로 동작하는지 확인한다.

이상적으로는 풀 리퀘스트가 모든 CI 플랫폼에서 통과되어야 한다. 이는 모든 테스트가 성공하고 린트 에러가 없음을 의미한다. 하지만 특정 플랫폼에서 CI 인프라 자체가 실패하거나, 일명 "불안정한" 테스트가 실패하는 경우도 드물지 않다. 각 CI 실패는 원인을 파악하기 위해 수동으로 검토해야 한다.

CI는 풀 리퀘스트를 열면 자동으로 시작되지만, CI 실행을 재시작할 수 있는 권한은 코어 메인테이너에게만 있다. CI가 잘못된 결과를 보여준다고 판단되면, 메인테이너에게 테스트를 재시작해 달라고 요청하면 된다.