기여 방법

기여자 라이선스 계약 (CLA)

코드 패치를 수락하려면 개인 또는 기업 기여자 라이선스 계약 (CLA)을 제출해야 합니다.

  • 원본 소스 코드를 작성하는 개인이고 지적 재산권을 확신하는 경우 개별 CLA를 제출하세요.
  • 회사에서 일하는 경우 기업 CLA를 제출하여 이 클라이언트 라이브러리에 작업을 제공할 수 있음을 나타내야 합니다.

위의 두 링크 중 하나를 클릭하여 적절한 CLA에 액세스한 다음 서명한 후 반환하는 방법에 대한 안내를 확인하세요. 신청서가 접수되면 공식 참여자 목록에 추가될 수 있습니다.

패치 제출 개요

이 프로젝트에 코드를 기여하려면 다음 일반 단계를 따르세요.

  1. 위에 설명된 대로 기여자 라이선스 계약에 서명합니다.
  2. 토론방에 참여하세요.
  3. 개발 환경을 설정합니다.
  4. GitHub Issue Tracker에서 각 변경 세트를 문제 (버그 신고 또는 기능 요청)와 연결합니다. 아직 문제가 없다면 새 문제를 만들고 본인에게 할당합니다.
  5. 코드를 체크아웃하고 codereview.appspot.com에서 새 문제를 생성하고 코드 검토 프로세스를 완료합니다. 이러한 모든 프로세스에 대한 자세한 안내는 아래에 나와 있습니다.
  6. 코드 검토 및 승인이 완료되면 코드를 커밋합니다. 공식 기여자가 아닌 경우 참여자는 변경 세트를 공식 저장소로 가져옵니다.

Google에서는 다음과 같은 도구와 절차를 사용합니다.

  • 버전 제어 시스템으로 Git을 사용합니다.
  • Google에서는 빌드 시스템과 바이너리 배포 시스템에 Maven을 사용합니다.
  • Google에서는 코드 검토에 codereview.appspot.com을 사용합니다. 하지만 codereview.appspot.com 도구에서 'issue'라는 용어는 코드 검토 요청을 의미하고 GitHub Issue Tracker에서 'issue'는 기능 요청 또는 버그 신고입니다.

Eclipse 개발자인 경우 Eclipse에서 자동으로 처리되는 .settings 디렉터리에 지정된 프로젝트별 코드 형식을 사용합니다.

개발 환경 설정

기본 요건

  1. 자바 6을 설치합니다. JAVA_HOME 변수를 설정해야 할 수도 있습니다.
  2. Maven을 설치합니다. 이 문서에서는 Maven 명령어에 대한 기본 지식이 있다고 가정합니다.
  3. 선택사항: Android SDK를 설치하고 ANDROID_HOME 변수를 Android의 설치 위치로 설정합니다.
  4. Git을 설치합니다.

Git 설정

git config 명령어를 사용하여 기본 표시 이름과 이메일 주소를 설정합니다.

git config --global user.name "YOUR NAME"
git config --global user.email "YOUR EMAIL ADDRESS"

Git에서 GitHub로 인증

GitHub에서 코드를 체크아웃하려면 HTTP 또는 SSH를 사용하여 GitHub에 인증해야 합니다. 아래 안내를 따르기 전에 HTTPS 또는 SSH 클론을 시작하는 방법에 대한 GitHub instructions를 읽어보세요. Git에 대한 일반적인 내용은 Pro Git 리소스가 필요합니다.

코드 체크아웃

HTTPS 사용

개발 'master' 브랜치에서 라이브러리 저장소를 체크아웃하려면 다음 명령어를 실행합니다.

git clone https://github.com/google/google-api-java-client.git

SSH 사용

개발 'master' 브랜치에서 라이브러리 저장소를 확인하려면 GitHub 저장소에 대한 쓰기 액세스 권한이 있는지 확인한 후 다음 명령어를 실행합니다.

git clone git@github.com:google/google-api-java-client.git

대체 브랜치(예: 1.12)로 전환하려면 다음을 실행합니다.

git checkout --track origin/1.12

마스터 브랜치로 다시 전환하려면 다음 안내를 따르세요.

git checkout master

GitHub 저장소에서 최신 변경사항을 가져오고 로컬 작업 트리를 최신 커밋으로 업데이트하려면 다음을 실행합니다.

git pull

Maven

Google Play 서비스 설치

프로젝트를 처음 설정하는 경우 google-play-services.jar 파일을 설치해야 합니다. 방법은 다음과 같습니다.

  1. Eclipse를 실행하고 Window > Android SDK Manager를 선택하거나 명령줄에서 android를 실행합니다.
  2. 패키지 목록 하단으로 스크롤하여 Extras > Google Play 서비스를 선택합니다.
mvn install:install-file \
           -Dfile=$ANDROID_HOME/extras/google/google_play_services/libproject/google-play-services_lib/libs/google-play-services.jar \
           -DgroupId=com.google.android.google-play-services \
           -DartifactId=google-play-services \
           -Dversion=1 \
           -Dpackaging=jar

프로젝트 컴파일

mvn clean install

Maven은 컴파일된 바이너리를 로컬 저장소 (예: ~/.m2/repository)에 설치합니다. Maven 중앙 저장소에서 가져오기 전에 해당 저장소에서 바이너리를 검색합니다.

참고: 이 라이브러리는 google-http-java-client 및 google-oauth-java-client에 종속됩니다. 아직 Maven Central에 출시되지 않은 세 라이브러리 모두의 새 버전에서 작업할 때는 다음 순서로 컴파일해야 합니다.

  1. google-http-java-client
  2. google-oauth-java-client
  3. google-api-java-client 이 순서로 컴파일하면 Maven에서 종속 라이브러리 컴파일을 위해 컴파일된 바이너리를 선택합니다.

코드 검토 프로세스

upload.py 스크립트 다운로드

upload.py 스크립트를 다운로드하고 필요에 따라 PATH에 추가합니다.

upload.py를 처음 실행하면 애플리케이션 비밀번호를 입력하라는 메시지가 표시됩니다.

Email (login for uploading to codereview.appspot.com): your_email_address@yourdomain.com
Password for your_email_address@yourdomain.com:

검토를 위해 코드 준비 중

검토를 위해 코드를 전송하기 전에 Clirr를 실행하여 코드의 이전 버전과의 호환성 문제를 포착해야 합니다. 오류가 보고되면 이를 수정하거나 clirr-ignored-differences.xml 파일을 업데이트해야 합니다.

mvn -q clirr:check

FindBugs 도구를 실행하여 코드의 버그를 포착해야 합니다. 오류가 보고되면 오류를 수정하거나 findbugs-embed.xml 파일을 업데이트해야 합니다. FindBugs는 매우 느립니다.

mvn findbugs:check

변경사항이 모든 테스트를 통과하면 색인 (Git 스테이징 영역)에 변경사항을 추가합니다.

git add .

추가, 수정 또는 삭제한 모든 파일이 색인에 반영되는지 다시 확인합니다.

git status

git status 출력에서 '커밋할 변경사항' 섹션을 확인합니다.

코드 검토 시작

검토 준비가 되면 codereview.appspot.com에서 새 문제를 생성합니다. 

upload.py --rev=HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

추가로 변경한 후 새 변경사항을 스테이징합니다. 새 패치(예: 발행 번호 123456)를 업로드하려면 다음 명령어를 실행합니다. 

upload.py --rev=HEAD -i 123456

더 많은 옵션을 보려면 upload.py --help를 실행합니다.

일반적인 GitHub 워크플로를 선호한다면 GitHub 저장소를 포크하고 이 새로운 기능이나 버그 수정을 위한 브랜치를 만들었을 것입니다. 자체 포크에서 코드 검토 요청을 보낼 때는 포크가 업스트림 저장소와 동기화되어 있는지 확인하세요. 자세한 내용은 포크 동기화 방법에 관한 GitHub 도움말을 참고하세요.

로컬에서 커밋된 변경 세트에도 upload.py를 사용할 수 있습니다.

upload.py --rev=upstream/master:HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

코드 검토자

코드 검토자인 경우 승인하기 전에 변경 집합을 가져와 테스트한 다음 변경 집합을 커밋하고 원격 저장소에 푸시합니다.

변경 집합 가져오기

오류를 조기에 포착하려면 원격 저장소에서 작업 트리로 최신 변경사항을 가져와야 합니다. 작업 트리가 깨끗하고 색인이 비어 있는지 확인합니다.

원격 저장소에서 최신 커밋을 가져오고 병합하려면 다음 안내를 따르세요.

git pull

작업 트리와 색인의 내용을 확인하려면 다음 안내를 따르세요.

git status

패치를 로컬 Git 클론으로 가져오려면 다음 안내를 따르세요.

  1. codereview.appspot.com에서 문제를 엽니다.
  2. 문제가 되는 패치는 패치 사양의 오른쪽 상단에서 'Download 원시'를 찾습니다.
  3. 'raw'를 클릭하여 가져올 파일의 URL을 가져옵니다.
  4. 원시 diff 파일을 issue123456.diff와 같은 이름으로 로컬 머신에 저장합니다.
  5. 로컬 Git 작업 트리로 이동하고 patch 명령어를 사용하여 차이를 적용합니다.
patch -p1 < issue123456.diff

올바른 차이를 가져왔는지 다시 확인하려면 작업 트리에서 git diff를 실행합니다.

변경 세트 테스트

테스트를 실행하고 설치하려면 다음 명령어를 사용하세요.

mvn clean install checkstyle:check

codereview.appspot.com에서 변경사항 세트 승인

일반적으로 코드 검토자가 코드가 준비되었다고 충족할 때까지 코드를 GitHub 저장소로 푸시할 수 없습니다. 이 시점에서 규칙은 'LGTM' (Looks Good To Me) 메시지로 응답하는 것입니다.

코드 커밋

중요: 코드를 커밋하기 전에 최신 변경사항을 작업 트리로 가져오고 작업 트리를 GitHub 저장소의 최신 커밋으로 업데이트하세요.

git pull

충돌이 있으면 문제를 해결한 후 모든 테스트를 다시 통과해야 합니다.

로컬에서 코드를 커밋하려면 다음을 실행합니다. 

git commit

다음과 같은 메시지를 입력합니다 (GitHub Issue Tracker에 나열된 문제 # 123을 수정하거나 구현한다고 가정).

#123: NullPointerException when passing null to processFoo()
http://codereview.appspot.com/123456/

첫 번째 콜론과 설명 앞:

  • Issue Tracker에서 문제가 해결되었다면 다음과 같이 문제 번호를 포함하세요.
  • 특정 브랜치의 변경사항인 경우 브랜치 번호를 포함하세요.
  • 내가 이 커밋의 committer 역할을 되지만, 변경사항 작성자를 author (--author=<author>)로 표시하여 기여도를 부여하세요.

설명 다음에는 항상 codereview 사이트에 문제 링크를 포함합니다. 이 링크가 없으면 커밋과 관련된 코드 검토를 알아낼 수 있는 편리한 방법이 없으므로 이 링크가 중요합니다. 이는 토론 기록을 유지하는 데 유용합니다.

GitHub 저장소에 변경사항을 푸시하려면 다음 안내를 따르세요.

git push

git push 중에 업데이트 거부에 관한 오류 메시지가 표시되면 (git pull을 실행하지 않았을 수 있음) 최신 변경사항과 병합하여 변경사항을 원격 저장소에 푸시하는 방법은 다음과 같습니다.

git pull
git commit
git push

문제 종료

코드 검토 도구에서 문제를 종료해야 합니다. 방법은 다음과 같습니다.

  1. codereview.appspot.com에서 문제를 선택합니다.
  2. 왼쪽 상단에서 'Id' 앞에 있는 'X'를 클릭합니다.

변경 세트 패치 해제

어떤 이유로든 가져온 변경 세트를 커밋하지 않으려면 다음 명령어를 사용하여 삭제합니다. 주의: 말 그대로 모든 로컬 변경사항이 삭제됩니다. 

git checkout -- .