오픈 소스에 기여

이 문서에서는 예제를 통해 오픈 소스 프로젝트에 기여하는 방법을 학습합니다. github/docs 리포지토리에 기여하는 방법을 안내합니다. 리포지토리에 익숙해 지고, 기여할 영역을 찾고, 끌어오기 요청을 만들고 제출하며, 유지 관리자와 협력하여 변경 내용을 승인하는 등의 방법이 있습니다.

프로젝트 가이드라인을 통해 목표 방향 지정

시작하기 전에, 프로젝트의 지침과 요구 사항을 이해하는 것이 중요합니다.

지침이 중요한 이유

각 프로젝트에는 따라야 하는 고유한 규칙, 코딩 표준, 기여 프로세스가 있습니다.

• 코드 스타일 및 서식 지정 요구 사항: 코드의 서식 지정 방법, 명명 규칙, 린팅 규칙
• 테스트 지침: 테스트 실행 방법, 새 기능에 필요한 테스트, 테스트 규칙
• 끌어오기 요청 프로세스: 끌어오기 요청 구성 방법, 포함할 정보, 검토 기대 사항
• 개발 환경 설정: 로컬 개발 환경 설정 방법, 필수 종속성, 빌드 프로세스
• 이슈 보고: 버그 보고, 기능 요청, 질문 방법
• 커뮤니케이션 채널: 질문, 변경 내용 논의, 유지 관리자에게 도움 요청 등을 진행할 수 있는 공간

이러한 내용을 읽는 데 시간이 걸리면 사용자와 유지 관리자 모두의 시간을 절약할 수 있고, 기여가 수락될 가능성도 높아집니다.

지침 찾기

이러한 가이드라인과 요구 사항에 액세스하려면 Insights 탭의 Community Standards 체크리스트로 이동하세요. 예시로, github/docs 커뮤니티 표준을 사용할 수 있습니다.

• 추가 정보: 프로젝트 개요를 제공합니다. 콘텐츠는 다양할 수 있지만, 추가 정보는 사용자와 기여자가 프로젝트가 무엇이고 어떻게 사용하는지 빠르게 이해하는 데 도움이 되며, 다른 문서에 대한 링크도 포함되어 있습니다.

• 사용 규정: 프로젝트 기여자 및 커뮤니티 구성원에게 요구되는 행동 기준을 정의하며, 위반 시 기대되는 절차와 대응 방법을 규정합니다.

• 기여: 프로젝트 기여자를 위한 가이드라인과 지침을 제공합니다. 명확한 기대치를 설정하고 일관된 협업을 장려하여 기여 프로세스를 보다 간소화할 수 있습니다.

• 라이선스: 다른 사용자가 코드를 사용, 수정, 배포할 수 있는 방법을 법적으로 정의합니다. 저작권 및 사용 권한을 명확히 함으로써 유지 관리자와 사용자를 모두 보호합니다.

  • 예를 들어, github/docs 리포지토리의 문서는 Creative Commons 라이선스를 사용합니다. 이 라이선스 유형은 창의적인 작업을 위해 특화된 라이선스 유형입니다. github/docs의 소프트웨어 코드는 MIT 라이선스에 따라 적용됩니다. 이 라이선스는 누구나 포함된 코드를 사용할 수 있도록 허용된 라이선스입니다.
  • 라이선스 선택 도구를 통해 다른 일반적인 라이선스 유형에 대해 알아볼 수 있습니다.

• 보안 정책: 리포지토리의 유지 관리자에게 보안 취약성을 보고하는 지침을 제공합니다.

github/docs 리포지토리에 제공된 각 리소스를 꼼꼼히 검토합니다.

기여할 영역 찾기

프로젝트에 처음 기여할 때는 문서 개선 또는 작은 버그 보고서와 같은 사소한 수정부터 시작하여 codebase 및 기여자 워크플로를 숙지하는 데 도움이 될 수 있습니다. 이 예시에서는 help wanted 및 good first issue 레이블이 붙은 이슈를 찾아 외부 기여자에게 열려 있는 특정 이슈를 확인합니다. 그런 다음, Copilot을 사용하여 이슈의 컨텍스트를 파악할 수 있습니다.

1. github/docs 리포지토리의 Issues 탭으로 이동한 다음, Labels 필터를 사용하고 "help wanted"를 선택하면 유지 관리자가 커뮤니티 도움이 필요하다고 특별히 표시한 열려 있는 문제를 볼 수 있습니다.

2. 이슈 목록을 살펴보고, 해결하고 싶은 이슈를 찾아보세요.

3. GitHub의 페이지 오른쪽 위에서 검색 창 옆에 있는 단추를 클릭합니다.

   Copilot Chat의 전체 페이지 몰입형 모드가 표시됩니다.

4. 프롬프트 상자에 다음 프롬프트를 입력합니다.

   Text

   Can you summarize the key points and next steps from this issue?
   

5. Copilot이 제공한 컨텍스트와 다른 기여자 및 유지 관리자의 댓글을 함께 읽어보고, 작업하고 싶은 이슈인지 확인합니다. 구체적인 질문이 있다면, 이슈 내에서 직접 질문하거나, 해당 프로젝트의 Discord, IRC, Slack에서 물어볼 수 있습니다.

프로젝트의 고유한 복사본 만들기

이제 기여를 시작할 준비가 되었습니다. 리포지토리를 직접 수정할 권한이 없으므로, 먼저 포크를 만들어야 합니다. 포크는 리포지토리의 개인 복사본으로, 여기에서 안전하게 변경 내용을 적용하고, 유지 관리자의 검토를 위해 다시 제출할 수 있습니다. 이 예시에서는 github/docs 리포지토리를 포크하는 과정을 안내합니다.

1. https://github.com/github/docs에서 GitHub Docs 프로젝트로 이동합니다.

2. 페이지의 오른쪽 상단에서 Fork(포크)를 클릭합니다.

3. "소유자"에서 드롭다운 메뉴를 선택하고 포크된 리포지토리의 소유자를 선택합니다.

4. 기본적으로 포크의 이름은 업스트림 리포지토리와 동일합니다. 필요에 따라 포크를 더 구분하려면, "리포지토리 이름" 필드에 이름을 입력합니다.

5. 필요에 따라 ‘설명’ 필드에 포크 설명을 입력합니다.

6. 필요에 따라 DEFAULT 분기만 복사를 선택합니다.

   오픈 소스 프로젝트에 기여하는 것과 같은 많은 포크 시나리오의 경우 기본 분기만 복사하면 됩니다. 이 옵션을 선택하지 않으면, 모든 분기가 새 포크로 복사됩니다.

7. 포크 만들기를 클릭합니다.

프로젝트의 포크 복제

이제 계정에 github/docs 리포지토리의 포크가 생겼지만, 변경 작업을 시작하려면 이를 로컬 컴퓨터로 가져와야 합니다.

1. GitHub에서 github/docs 리포지토리의 포크로 이동합니다.

2. 파일 목록 위에서 코드를 클릭합니다.

   

3. 리포지토리의 URL을 복사합니다.

   • HTTPS를 사용하여 리포지토리를 복제하려면 "HTTPS"에서 을 클릭합니다.

   • 조직의 SSH 인증 기관에서 발급한 인증서를 포함하여 SSH 키를 사용하여 리포지토리를 복제하려면 SSH를 클릭한 다음, 을 클릭합니다.

   • GitHub CLI를 사용하여 리포지토리를 복제하려면 GitHub CLI 를 클릭한 다음, 을 클릭합니다.

     

4. Mac 또는 Linux에서 터미널을 엽니다. Windows에서 Git Bash를 엽니다.

5. 현재 작업 디렉터리를 복제 대상 디렉터리의 위치로 변경합니다.

6. git clone을 입력한 다음 이전에 복사한 URL을 붙여넣습니다. 그러면 다음과 같이 되며, 여기서 YOUR-USERNAME 대신 GitHub 사용자 이름을 사용합니다.

   Shell

   git clone https://github.com/YOUR-USERNAME/docs
   

7. Enter 키를 누릅니다. 로컬 복제본이 만들어집니다.

토픽 분기에서 변경 작업하기

이제 변경을 시작할 차례입니다! 시작하기 전에, 포크에서 설명적인 이름을 가진 토픽 분기를 만드는 것이 좋습니다. 토픽 분기를 사용하면 리포지토리의 기본 분기와 별도로 작업을 유지할 수 있습니다.

git checkout -b YOUR_TOPIC_BRANCH

git checkout -b YOUR_TOPIC_BRANCH

토픽 분기로 전환한 후, 즐겨 찾는 텍스트 편집기 또는 IDE를 열고 코딩을 시작합니다. 다음 모범 사례를 따르세요:

• Copilot을 사용하여 코드 제안을 제공하면 변경 내용에 대한 확신을 가질 수 있습니다.
• 코드를 문서화하고 테스트를 작성합니다. 종종 간과되지만, 기여가 병합되도록 돕는 중요한 요소입니다.
• 구현 요구 사항을 더 잘 이해할 수 있도록 해당 이슈에 대해 Copilot에게 질문하세요.
• Copilot을 사용하여 변경 내용을 검토하고, 프로젝트의 코딩 스타일과 문서 요구 사항을 충족하는지 확인하세요.
• Copilot을 사용해 로컬 머신에서 프로젝트를 빌드하고 테스트하기 위한 지침을 활용해 보세요.

변경 내용 커밋 및 푸시

변경 내용이 준비되면, 리포지토리에서 스테이징하고 커밋할 수 있습니다. 커밋 메시지를 작성할 때는, 커밋이 수행하는 작업을 요약하는 50자 미만의 명확하고 간결한 커밋 제목을 사용합니다. 가능하다면 관련 변경 내용을 단일 커밋으로 그룹화하고, 관련 없는 변경 내용은 별도의 커밋으로 분리하세요.

git add .
git commit -m "a short description of the change"

git add .
git commit -m "a short description of the change"

가독성을 높이기 위해, 커밋 설명 줄은 72자 미만으로 유지하는 것이 좋습니다. 로컬 변경 내용 커밋을 완료했고 이를 GitHub에 푸시할 준비가 되면, 변경 내용을 원격으로 푸시합니다.

git push

git push

끌어오기 요청 제출하기

GitHub에 변경 내용을 푸시했다면, 끌어오기 요청을 열 준비가 된 것입니다. 분기에서 변경한 내용을 완료하지 않았더라도, 검토를 위해 끌어오기 요청을 열 수 있습니다. 기여 프로세스 초기에 끌어오기 요청을 열면 유지 관리자가 변경 내용을 인지하고, 변경 내용에 대한 초기 피드백을 제공할 수 있습니다.

1. GitHub에서 포크된 리포지토리로 이동합니다. 예들 들어 https://github.com/YOUR-USERNAME/docs입니다.
2. 최근에 푸시된 분기에 대해 "Compare & pull request"라는 프롬프트가 표시됩니다. 이 단추를 클릭하십시오.
3. 만약 보이지 않는다면, "Pull requests" 탭으로 이동해 "New pull request"를 클릭합니다.
4. 기본 리포지토리가 github/docs이고, 기본 분기가 주 분기인지 확인합니다(예: main).
5. 헤드가 자신의 포크(YOUR-USERNAME/docs)이고, 비교 분기가 자신의 분기인지 확인합니다.
6. 끌어오기 요청의 제목과 설명을 입력합니다. 설명에는 이 끌어오기 요청이 닫을 이슈를 참조해야 합니다. 예들 들어 Closes: #15입니다. 이렇게 하면 끌어오기 요청에 필요한 컨텍스트를 제공할 수 있고, 끌어오기 요청이 병합되면 해당 이슈가 자동으로 닫힙니다.

프로젝트 유지 관리자와 협력하기

끌어오기 요청이 제출되면, 다음 단계는 프로젝트 유지 관리자가 검토하고 피드백을 제공하는 것입니다. 프로젝트 유지 관리자는 codebase의 스타일이나 아키텍처에 맞추기 위해 변경 내용을 요청할 수 있으며, 경우에 따라 작업의 상당 부분을 리팩터링해야 할 수도 있습니다.

• 끌어오기 요청에 대한 피드백을 받으면, 비판이 다소 날카롭게 느껴지더라도 신속하고 전문적으로 응답하세요. 유지 관리자는 일반적으로 코드 품질에 중점을 둡니다.
• 끌어오기 요청에 변경 요청이 있다면, 변경 내용을 해결하기 위해 새 끌어오기 요청을 열지 마세요. 기존 끌어오기 요청을 열어 변경 내용을 적용하면, 유지 관리자가 컨텍스트를 잃지 않도록 방지할 수 있습니다.
• 끌어오기 요청이 몇 주 동안 해결되지 않은 상태로 유지되는 경우, 정중하게 댓글로 피드백을 요청하세요. 다만, 유지 관리자의 핸들을 직접 언급하지는 마세요. 유지 관리자는 종종 풀타임 업무와 오픈 소스 작업을 병행하기 때문에, 그들의 시간 제약을 이해하는 것이 더 나은 협업을 이끕니다.
• 기여가 받아들여지지 않더라도, 다음번 기여 시 참고할 수 있는 맥락을 얻을 수 있도록 유지 관리자에게 피드백을 요청하세요.

다음 단계

이제 어떤 이슈를 선택해 작업할지, 유지 관리자가 병합하고 싶어 하는 기여를 어떻게 만들지, 그리고 끌어오기 요청 검토 과정을 어떻게 진행할지를 알게 되었습니다. GitHub의 오픈 소스 커뮤니티는 여러분의 고유한 관점과 기술을 기다리고 있습니다. 새로운 프로젝트를 찾아 흥미로운 이슈를 식별하고, 기여를 시작해 보세요.