Go 기여 가이드

1 개요

Contribution Guide

기여 가이드

https://go.dev/doc/contribute

---

Go 프로젝트는 모든 기여자를 환영합니다.

본 문서는 Go 프로젝트에 기여하는 과정을 안내하는 가이드로, 다른 오픈소스 프로젝트에서 사용하는 방식과 조금 다릅니다. Git과 Go에 대한 기본적인 이해가 있다고 가정합니다.

여기에 있는 정보 외에도 Go 커뮤니티는 CodeReview 위키 페이지를 유지관리합니다. 리뷰 프로세스를 배우면서 자유롭게 위키에 기여해 보세요.

gccgo 프론트엔드는 다른 곳에 있습니다 gccgo에 기여하기를 참조하세요.

2 기여자 되기

2.1 개요

첫 번째 단계는 Go 기여자로 등록하고 환경을 구성하는 것입니다. 필수 단계의 체크리스트는 다음과 같습니다.

• 0단계: Go에 기여하는 데 사용할 단일 Google 계정을 결정합니다. 다음 모든 단계에 해당 계정을 사용하고 git 해당 계정의 이메일 주소로 커밋을 생성하도록 구성되어 있는지 확인하세요.
• 1단계: CLA(기여자 라이선스 계약)에 서명하고 제출합니다 .
• 2단계: Go Git 저장소에 대한 인증 자격증명을 구성합니다. go.googlesource.com을 방문하여 페이지 오른쪽 상단 메뉴 표시줄에서 '비밀번호 생성'을 클릭하고 지침을 따르세요.
• 3단계: 이 페이지를 방문하여 Go 팀에서 사용하는 코드 리뷰 도구인 Gerrit에 등록하세요. CLA 및 등록은 귀하의 계정에 대해 한 번만 수행하면 됩니다.
• 4단계: go install golang.org/x/review/git-codereview@latest를 실행하여 git-codereview를 설치합니다.

이러한 단계를 수행해주는 자동화 도구가 있어서, 다음과 같이 실행해도 됩니다.

$ go install golang.org/x/tools/cmd/go-contrib-init@latest
$ cd /code/to/edit
$ go-contrib-init

이 장의 나머지 부분에서는 이러한 지침에 대해 자세히 설명합니다. (수동으로 또는 도구를 통해) 위 단계를 완료한 경우 '코드를 기여하기 전에'로 이동하세요.

2.2 0단계: Google 계정 선택

Go에 대한 기여는 특정 이메일 주소를 가진 Google 계정을 통해 이루어집니다. 프로세스 전체와 이후의 모든 기여에 대해 동일한 계정을 사용해야 합니다. 개인 주소를 사용할지 회사 주소를 사용할지 결정해야 할 수도 있습니다. 선택은 기여자가 작성하고 제출할 코드에 대한 저작권을 누가 소유하는지에 따라 달라집니다. 사용할 계정을 결정하기 전에 이 주제를 고용주와 논의할 수 있습니다.

Google 계정은 Gmail 이메일 계정, G Suite 조직 계정 또는 외부 이메일 주소와 연결된 계정일 수 있습니다. 예를 들어 G Suite를 통해 관리되지 않는 기존 회사 이메일을 사용해야 하는 경우 기존 이메일 주소와 연결된 계정을 만들 수 있습니다.

또한 선택한 이메일 주소를 사용하여 커밋을 생성하도록 Git 도구가 구성되어 있는지 확인해야 합니다. Git을 전역적으로(모든 프로젝트의 기본값으로) 설정하거나 로컬로(단일 특정 프로젝트의 경우) 설정할 수 있습니다. 다음 명령어를 사용하여 현재 설정을 확인할 수 있습니다.

$ git config --global user.email   # 현재 전역 설정 확인
$ git config user.email            # 현재 로컬 설정 확인

설정된 주소를 변경하려면:

$ git config --global user.email name@example.com   # 전역 설정 변경
$ git config user.email name@example.com            # 로컬 설정 변경

2.3 1단계: 기여자 라이선스 계약

Go 프로젝트에 첫 번째 변경사항을 보내기 전에 다음 두 CLA 중 하나를 완료해야 합니다. 어떤 CLA에 서명해야 하는지는 기여자의 저작물에 대한 저작권 소유자가 누구인지에 따라 다릅니다.

• 기여자가 저작권 소유자인 경우 온라인으로 완료할 수 있는 개별 기여자 라이센스 계약에 동의해야 합니다.
• 기여자의 조직이 저작권 소유자인 경우 해당 조직은 기업 기여자 라이선스 계약에 동의해야 합니다.

Google Developers Contributor License Agreements 웹사이트 에서 현재 서명된 계약을 확인하고 새 계약에 서명할 수 있습니다. 기여자의 기여에 대한 저작권 보유자가 이미 다른 Google 오픈소스 프로젝트와 관련하여 계약을 완료한 경우 다시 계약을 완료할 필요가 없습니다.

제출하려는 코드의 저작권 소유자가 변경된 경우(예: 새 회사를 대신하여 코드 기여를 시작하는 경우) golang-dev 메일링 리스트(golang-dev@googlegroups.com)로 메일을 보내주세요. 이를 통해 상황을 알 수 있으므로 적절한 계약이 완료되었는지 확인할 수 있습니다.

2.4 2단계: Git 인증 구성

기본 Go 저장소는 Google이 호스팅하는 Git 서버인 go.googlesource.com에 있습니다. 웹 서버에서의 인증은 Google 계정을 통해 이루어지지만, 이에 액세스하려면 컴퓨터에서도 git을 설정해야 합니다. 다음과 같이하세요:

1. go.googlesource.com을 방문하여 페이지 오른쪽 상단 메뉴 표시줄에서 '비밀번호 생성'을 클릭하세요. 로그인을 위해 account.google.com으로 리디렉션됩니다.
2. 로그인하면 "Git 설정"이라는 제목의 페이지로 이동됩니다. 이 페이지에는 로컬로 실행될 때 Git이 고유한 인증 키를 보유하도록 구성하는 개인화된 스크립트가 포함되어 있습니다. 이 키는 SSH 키 작동 방식과 유사하게 서버에서 생성 및 저장되는 키와 쌍을 이룹니다.
3. 비밀 인증 토큰을 .gitcookies 파일에 저장하려면 터미널에서 이 스크립트를 로컬로 복사하고 실행하세요. Windows 컴퓨터를 사용하고 cmd를 실행하는 경우, 대신 노란색 상자의 지침에 따라 명령어를 실행해야 합니다. 그렇지 않으면 일반 스크립트를 실행하십시오.

2.5 3단계: Gerrit 계정 만들기

Gerrit은 Go 관리자가 코드 제출을 논의하고 검토하기 위해 사용하는 오픈소스 도구입니다.

계정을 등록하려면 go-review.googlesource.com/login/을 방문하여 위에서 사용한 것과 동일한 Google 계정을 사용하여 한 번 로그인하세요.

2.6 4단계: git-codereview 명령어 설치

Go에 대한 변경사항은 누가 변경했는지에 관계없이 승인되기 전에 리뷰되어야 합니다. git-codereview라는 커스텀 git 명령어를 사용하면 변경사항을 Gerrit으로 보내는 작업이 단순화됩니다.

다음을 실행하여 git-codereview 명령어를 설치합니다.

$ go install golang.org/x/review/git-codereview@latest

git 명령어가 찾을 수 있도록 git-codereview가 쉘 경로에 설치되어 있는지 확인하세요.

$ git codereview help

오류가 아닌 도움말 텍스트를 출력합니다. 오류가 출력되면 $GOPATH/bin가 $PATH에 있는지 확인하세요.

Windows에서는 git-bash를 사용할 때 git-codereview.exe가 git exec-path에 있는지 확인해야 합니다. git --exec-path를 실행하여 올바른 위치를 찾은 다음 심볼릭 링크를 생성하거나 $GOPATH/bin에서 이 디렉토리로 실행파일을 복사하세요.

3 코드를 기여하기 전에

프로젝트는 코드 패치를 환영하지만, 작업이 원활하게 진행되도록 중요한 변경사항에 대해서는 작업을 시작하기 전에 반드시 논의해야 합니다. 기여 의사를 알리기 위해 새로운 이슈를 등록하거나 기존 이슈를 맡는 방식으로 이슈 트래커에서 의사를 밝히는 것이 좋습니다.

3.1 기여할 곳

Go 프로젝트는 Go 언어의 소스 코드를 포함하는 메인 go 리포지토리와 다양한 도구 및 인프라를 포함하는 많은 golang.org/x/... 리포지토리로 구성되어 있습니다. 예를 들어, golang.org/x/pkgsite는 pkg.go.dev를 위한 것이고, golang.org/x/playground는 Go 플레이그라운드를 위한 것이며, golang.org/x/tools에는 Go 언어 서버(gopls)를 포함한 다양한 Go 도구들이 들어 있습니다. 모든 golang.org/x/... 저장소의 목록은 go.googlesource.com에서 확인할 수 있습니다.

3.2 이슈 트래커 확인

기여할 사항을 이미 알고 있거나 아이디어를 찾고 있다면, 이슈 트래커가 항상 첫 번째로 가야 할 곳입니다. 이슈는 분류되고 워크플로우를 관리하기 위해 분류됩니다.

대부분의 golang.org/x/... 리포도 메인 Go 이슈 트래커를 사용합니다. 그러나 이들 리포지토리 중 일부는 별도로 이슈를 관리하므로, 기여하고자 하는 리포지토리에 맞는 이슈 트래커를 확인해야 합니다.

대부분의 이슈는 다음의 워크플로우 레이블 중 하나로 표시됩니다:

• NeedsInvestigation: 이슈가 완전히 이해되지 않았으며, 근본 원인을 파악하기 위해 분석이 필요합니다.
• NeedsDecision: 이슈가 비교적 잘 이해되었지만, Go 팀이 아직 이를 해결할 최선의 방법을 결정하지 않았습니다. 코드를 작성하기 전에 결정을 기다리는 것이 좋습니다. 이 상태의 이슈에 관심이 있다면, 일정 시간이 지나도 결정이 내려지지 않았다면 이슈의 댓글에서 유지관리자에게 "핑"을 보내도 좋습니다.
• NeedsFix: 이슈가 완전히 이해되었으며 이를 해결하기 위한 코드를 작성할 수 있습니다.

GitHub의 검색 기능을 사용하여 도울 수 있는 이슈를 찾을 수 있습니다. 예시:

• 조사가 필요한 이슈: is:issue is:open label:NeedsInvestigation
• 수정이 필요한 이슈: is:issue is:open label:NeedsFix
• 수정이 필요하고 제안된 변경사항이 있는 이슈: is:issue is:open label:NeedsFix ("golang.org/cl" OR "go.dev/cl")
• 수정이 필요하고 제안된 변경사항이 없는 이슈: is:issue is:open label:NeedsFix NOT "golang.org/cl" NOT "go.dev/cl"

3.3 새로운 문제에 대한 이슈 열기

아주 사소한 변경사항을 제외하고 모든 기여는 기존 이슈와 연결되어야 합니다. 이슈를 열고 계획을 논의해보세요. 이 과정은 디자인을 검증하고, 작업의 중복을 방지하며, 아이디어가 언어와 도구의 목표에 부합하는지 확인할 기회를 제공합니다. 또한, 코드가 작성되기 전에 디자인이 건전한지 점검합니다. 코드 리뷰 도구는 고수준 논의를 위한 장소가 아닙니다.

작업을 계획할 때, Go 프로젝트는 주 저장소에 대해 6개월 개발 주기를 따른다는 점을 유의하세요. 각 주기의 후반 3개월은 버그 수정 및 문서 업데이트만 허용되는 기능 동결 기간입니다. 기능 동결 기간 동안에도 새로운 기여는 보낼 수 있지만, 동결이 끝날 때까지 병합되지 않습니다. 동결은 주 저장소 전체와 릴리스에 포함된 바이너리를 빌드하는 데 필요한 golang.org/x/... 저장소의 코드에도 적용됩니다. 표준 라이브러리와 go 명령어에 벤더링된 패키지 목록을 참조하세요.

언어, 라이브러리, 도구에 대한 중요한 변경사항(주 저장소와 모든 golang.org/x 저장소의 API 변경사항 및 go 명령어에 대한 명령줄 변경사항 포함)은 수락되기 전에 변경사항 제안 과정을 거쳐야 합니다.

민감한 보안 관련 문제(보안 관련 문제만!)는 security@golang.org로 보고해야 합니다.

4 GitHub을 통해 변경사항 보내기

GitHub 흐름에 익숙한 첫 기여자들은 Go 기여를 위해 동일한 프로세스를 사용할 것을 권장합니다. 비록 Go 유지관리자들이 코드 리뷰를 위해 Gerrit을 사용하지만, GitHub 풀 리퀘스트를 Gerrit과 동기화하는 Gopherbot이라는 봇이 만들어졌습니다.

GitHub 풀 리퀘스트를 평소와 같이 엽니다. 그러면 Gopherbot이 해당하는 Gerrit 변경목록(“CL”)을 생성하고, GitHub 풀 리퀘스트에 링크를 게시합니다. 풀 리퀘스트에 대한 업데이트도 Gerrit CL에 반영됩니다. CL에 누군가가 댓글을 달면, 그 댓글이 풀 리퀘스트에도 게시되어 알림을 받게 됩니다.

다음 사항들을 유의하세요:

• 리뷰어에게 응답하기 위해서는 Gerrit 계정이 필요합니다. 여기에는 제안된대로 피드백을 구현했을 경우 'Done'으로 마크하는 것이 포함됩니다. 열린 CL을 훑어보거나, 관심 있는 CL의 업데이트를 구독(별 아이콘 클릭)하거나, 다른 사람들의 CL을 리뷰하거나 +1을 주는 등의 방법으로 Gerrit에 익숙해지는 것이 좋습니다.
• 새로운 코드를 풀 리퀘스트에 업데이트하려면 브랜치에 푸시하면 됩니다. 더 많은 커밋을 추가하거나 리베이스 후 강제 푸시(둘 다 허용)할 수 있습니다.
• 요청이 수락되면 모든 커밋은 하나로 합쳐지며, 최종 커밋 설명은 풀 리퀘스트의 제목과 설명을 연결하여 구성됩니다. 개별 커밋의 설명은 폐기됩니다. 좋은 커밋 메시지 작성에 대한 몇 가지 제안을 참고하세요.
• 자세한 내용은 FAQ를 참조하세요.

5 Gerrit을 통해 변경사항 보내기

현재로서는 Gerrit와 GitHub를 완전히 동기화하는 것이 불가능하기 때문에, Gerrit을 배우는 것을 권장합니다. Gerrit은 다르지만 강력하며, 이를 익히면 흐름을 이해하는 데 도움이 될 것입니다.

5.1 개요

다음은 전체 프로세스 개요입니다:

• 1단계: go.googlesource.com에서 소스 코드를 클론하고, 안정적인지 확인하기 위해 컴파일하고 테스트합니다.

메인 Go 저장소에 변경사항을 적용하는 경우:

$ git clone https://go.googlesource.com/go
$ cd go/src
$ ./all.bash                                # 컴파일 및 테스트

golang.org/x/... 저장소(이 예시에서는 golang.org/x/tools)에 변경사항을 적용하는 경우:

$ git clone https://go.googlesource.com/tools
$ cd tools
$ go test ./...                             # 컴파일 및 테스트

• 2단계: master 브랜치에서 새 브랜치를 만들어 변경사항을 준비합니다. 변경사항을 커밋하려면 git codereview change를 사용합니다. 이는 브랜치에 하나의 커밋을 생성하거나 수정합니다.

$ git checkout -b mybranch
$ [파일 편집...]
$ git add [파일들...]
$ git codereview change   # 브랜치에 커밋 생성
$ [다시 편집...]
$ git add [파일들...]
$ git codereview change   # 새로운 변경사항으로 기존 커밋 수정
$ [기타.]

• 3단계: 편집한 패키지의 테스트를 실행하거나 all.bash를 다시 실행하여 변경 사항을 테스트합니다.

메인 Go 저장소에서:

$ ./all.bash    # 재컴파일 및 테스트

golang.org/x/... 저장소에서:

$ go test ./... # 재컴파일 및 테스트

• 4단계: git codereview mail(이름은 그렇지만, 이메일을 사용하지는 않음)을 사용하여 변경사항을 Gerrit에 리뷰 요청으로 보냅니다.

$ git codereview mail     # Gerrit에 변경사항 전송

• 5단계: 리뷰 후, 동일한 커밋에 변경사항을 적용하고 다시 Gerrit에 전송합니다:

$ [파일 편집...]
$ git add [파일들...]
$ git codereview change   # 동일한 커밋 업데이트
$ git codereview mail     # 다시 Gerrit에 전송

이 섹션의 나머지 부분은 이러한 단계를 자세히 설명합니다.

5.2 1단계: 소스코드 클론

최근 버전의 Go 설치에 더하여, 올바른 리포지토리에서 소스를 체크아웃한 로컬 사본이 필요합니다. Go 소스 리포지터리는 GOPATH 외부에 어디든지 로컬 파일 시스템에 체크아웃할 수 있습니다. go.googlesource.com(GitHub 아님)에서 클론하십시오.

메인 Go 리포지토리:

$ git clone https://go.googlesource.com/go
$ cd go

golang.org/x/... 리포지토리:

(예: golang.org/x/tools):

$ git clone https://go.googlesource.com/tools
$ cd tools

5.3 2단계: 새 브랜치에서 변경사항 준비

각 Go 변경사항은 master 브랜치에서 생성된 별도의 브랜치에서 수행해야 합니다. 일반적인 git 명령어를 사용하여 브랜치를 생성하고 변경사항을 스테이징 영역에 추가할 수 있습니다:

$ git checkout -b mybranch
$ [파일 편집...]
$ git add [파일들...]

변경사항을 커밋하려면, git commit 대신 git codereview change를 사용하세요.

$ git codereview change
($EDITOR 열림)

커밋 설명은 평소 사용하는 편집기에서 수정할 수 있습니다. git codereview change 명령어는 자동으로 아래쪽에 고유한 Change-Id 줄을 추가합니다. 이 줄은 Gerrit이 동일한 변경사항의 연속적인 업로드를 매치하는 데 사용됩니다. 이 줄을 수정하거나 삭제하지 마세요. Change-Id는 다음과 같이 생겼습니다:

Change-Id: I2fbdbffb3aab626c4b6f56348861b7909e3e8990

이 도구는 또한 소스 코드에 go fmt이 실행되었는지, 커밋 메시지가 제안된 형식을 따르는지 확인합니다.

파일을 다시 편집해야 하는 경우, 새로운 변경사항을 스테이징하고 git codereview change를 다시 실행할 수 있습니다. 각 후속 실행은 기존 커밋을 변경하지 않고 Change-Id를 유지하면서 수정합니다.

각 브랜치에 항상 단일 커밋만 유지해야 합니다. 실수로 더 많은 커밋을 추가한 경우, git rebase를 사용하여 이를 단일 커밋으로 합칠(squash) 수 있습니다.