기여 방법

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

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

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

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

패치 제출 개요

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

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

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

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

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

개발 환경 설정

기본 요건

  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 안내를 읽어보세요. 일반적인 Git에 대해 자세히 알아보려면 Pro Git이 적합합니다.

코드 체크아웃

HTTPS 사용

개발 브랜치에서 라이브러리 저장소를 확인하려면 다음 명령어를 실행합니다.

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

SSH 사용

개발 브랜치의 라이브러리 저장소를 확인하려면 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-differents.xml 파일을 업데이트해야 합니다.

mvn -q clirr:check

코드에서 버그를 포착하려면 FindBugs 도구도 실행해야 합니다. 오류가 보고되면 오류를 수정하거나 findbugs-exclude.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 --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. '원시'를 클릭하여 가져올 파일의 URL을 가져옵니다.
  4. 원시 비교 파일을 issue123456.diff와 같은 이름으로 로컬 머신에 저장합니다.
  5. 로컬 Git 작업 트리로 이동하고 patch 명령어를 사용하여 차이를 적용합니다.
patch -p1 < issue123456.diff

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

변경사항 세트 테스트

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

mvn clean install checkstyle:check

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

일반적으로 코드 검토자가 코드가 준비될 때까지 GitHub 저장소에 코드를 푸시할 수 없습니다. 이 시점에서 규칙은 'LGTM&quot(Looks Good Me 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>)로 표시하여 작성자에게 크레딧을 부여하세요.

설명 뒤에는 항상 코드 검토 사이트에 문제 링크를 포함하세요. 이 링크가 없으면 커밋과 연결된 코드 검토를 파악할 수 있는 편리한 방법이 없기 때문에 중요합니다. 이는 토론 기록을 유지하는 데 유용합니다.

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

git push

git push 중에 업데이트가 거부되었다는 오류 메시지가 표시되면 (git pull 실행을 잊은 경우) 최신 변경사항과 병합하고 원격 저장소에 변경사항을 푸시하는 방법을 알아봅니다. 

git pull
git commit
git push

문제 해결

코드 검토 도구에서 문제를 종료해야 합니다. 다음 단계를 따르세요.

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

변경사항 세트 패치 취소

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

git checkout -- .