Как внести свой вклад

Лицензионные соглашения для участников (CLA)

Прежде чем мы сможем принять ваши исправления кода, вам необходимо предоставить индивидуальное или корпоративное лицензионное соглашение для участников (CLA):

  • Если вы являетесь частным лицом, пишущим исходный исходный код, и уверены, что являетесь владельцем интеллектуальной собственности, отправьте индивидуальное CLA .
  • Если вы работаете в компании, ваша компания должна предоставить корпоративный CLA, чтобы указать, что вам разрешено вносить свою работу в эту клиентскую библиотеку.

Перейдите по любой из двух ссылок выше, чтобы получить доступ к соответствующему CLA и инструкциям по его подписанию и возврату. Как только мы его получим, мы сможем добавить вас в официальный список участников.

Обзор отправки исправлений

Чтобы добавить код в этот проект, выполните следующие общие шаги:

  1. Подпишите лицензионное соглашение для участников, как описано выше.
  2. Присоединяйтесь к нашей дискуссионной группе .
  3. Настройте среду разработки .
  4. Свяжите каждый из ваших наборов изменений с проблемой (отчетом об ошибке или запросом функции) в нашем трекере проблем GitHub. Создайте новую задачу, если ее еще нет, и назначьте ее себе.
  5. Проверьте код, создайте новую задачу на codereview.appspot.com и завершите процесс проверки кода. Подробные инструкции по всем этим процессам приведены ниже.
  6. После того как ваш код будет проверен и вы получите одобрение, зафиксируйте его. Если вы не являетесь официальным участником, он поместит ваш набор изменений в официальный репозиторий.

Мы используем следующие инструменты и процессы:

  • В качестве системы контроля версий мы используем Git .
  • Мы используем Maven для системы сборки, а также бинарную систему распространения.
  • Мы используем codereview.appspot.com для проверки кода. (Но обратите внимание, что в инструменте codereview.appspot.com термин «проблема» означает запрос на проверку кода, а в GitHub Issue Tracker «проблема» — это запрос функции или отчет об ошибке.)

Если вы разработчик Eclipse, используйте форматирование кода для конкретного проекта, указанное в каталоге .settings, который автоматически обрабатывается Eclipse.

Настройка среды разработки

Предварительные условия

  1. Установите Яву 6 . Возможно, вам потребуется установить переменную JAVA_HOME .
  2. Установите Мавен . (В этом документе предполагается, что вы имеете базовые знания команд Maven.)
  3. Необязательно: установите Android SDK и задайте для переменной ANDROID_HOME место установки Android.
  4. Установите Гит .

Настройка Git

Используйте команду git config чтобы установить отображаемое имя и адрес электронной почты по умолчанию: 

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

Аутентификация с помощью GitHub из Git

Чтобы иметь возможность получить код из GitHub, вы должны пройти аутентификацию на GitHub с использованием HTTP или SSH. Прежде чем продолжить выполнение приведенных ниже инструкций, прочтите инструкции GitHub о том, как приступить к клонированию HTTPS или SSH. Если вы хотите узнать больше о Git в целом, Pro Git — хороший ресурс.

Проверяем код

Использование HTTPS

Чтобы получить доступ к репозиторию библиотеки в ветке разработки «master», выполните следующую команду: 

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

Мавен

Установите сервисы Google Play

При первой настройке проекта вам необходимо установить файл google-play-services.jar. Для этого:

  1. Запустите Eclipse и выберите «Окно» > «Менеджер Android SDK» или запустите android из командной строки.
  2. Прокрутите список пакетов вниз и выберите «Дополнительно» > «Службы 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-клиент
  2. Google-OAuth-Java-клиент
  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-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 для локально зафиксированных наборов изменений. 

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. Для рассматриваемого патча найдите «Загрузить в необработанном виде» в правом верхнем углу спецификации патча.
  3. Нажмите «raw», чтобы получить URL-адрес файла для импорта.
  4. Сохраните необработанный файл различий на локальном компьютере с именем, например, Issue123456.diff.
  5. Перейдите в локальное рабочее дерево Git и примените разницу с помощью команды patch :
patch -p1 < issue123456.diff

Чтобы еще раз проверить, что вы импортировали правильный diff, выполните git diff в своем рабочем дереве.

Тестирование набора изменений

Для запуска тестов и установки используйте следующую команду: 

mvn clean install checkstyle:check

Утверждение набора изменений на codereview.appspot.com

Как правило, код нельзя отправить в репозиторий GitHub, пока проверяющий код не убедится, что код готов. На этом этапе принято отвечать сообщением «LGTM» (выглядит хорошо для меня).

Фиксация кода

Важно: прежде чем зафиксировать свой код, внесите последние изменения в свое рабочее дерево и обновите рабочее дерево до последней фиксации из репозитория GitHub:

git pull

Если есть какие-либо конфликты, разрешите их, а затем убедитесь, что все тесты пройдены заново.

Чтобы зафиксировать код локально :

git commit

Введите сообщение, подобное следующему (при условии, что вы исправляете или реализуете проблему № 123, как указано в трекере проблем GitHub):

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

Перед первым двоеточием и описанием:

  • Если это решение проблемы в системе отслеживания ошибок , укажите номер проблемы, как показано.
  • Если это изменение для определенного филиала, укажите номер филиала.
  • Вы будете committer этого коммита, но, пожалуйста, отдайте должное автору изменения, отметив его как author ( --author=<author> ).

После описания всегда добавляйте ссылку на проблему на сайте codereview. Эта ссылка важна, поскольку без нее нет удобного способа выяснить код-ревью, связанный с фиксацией, что полезно для ведения истории обсуждения.

Чтобы отправить изменение в репозиторий GitHub:

git push

Если во время git push вы получаете сообщение об ошибке об отклонении обновлений (возможно, вы забыли запустить git pull ), выполните слияние с последними изменениями и отправку изменений в удаленный репозиторий:

git pull
git commit
git push

Закрытие проблемы

Обязательно закройте проблему в инструменте проверки кода. Для этого:

  1. Выберите проблему на codereview.appspot.com .
  2. Нажмите «X» в левом верхнем углу перед «Id».

Отключение набора изменений

Если по какой-то причине вы решите не сохранять импортированный набор изменений, используйте следующую команду, чтобы избавиться от него. Будьте осторожны : он буквально стирает все ваши локальные изменения.

git checkout -- .