Как помочь проекту

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

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

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

Общие сведения об отправке исправлений

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

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

Для этого мы используем следующие инструменты и процессы:

  • В качестве системы управления версиями мы используем Git.
  • В качестве системы сборки и распространения двоичных файлов мы используем Maven.
  • Для проверки кода мы используем codereview.appspot.com. (Обратите внимание, что в инструменте codereview.appspot.com термин "issue" означает запрос на проверку кода, а в системе отслеживания ошибок GitHub – запрос на добавление функции или отчет об ошибке.)

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

Как настроить среду разработки

Требования

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

Настройка 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

Чтобы проверить репозиторий библиотеки в ветке разработки 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 SDK) или введите android в командной строке.
  2. Прокрутите список пакетов вниз и выберите Extras (Дополнительно) > Google Play services (Сервисы 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, их нужно компилировать в следующем порядке:

  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-exclude.xml. (Обратите внимание, что FindBugs работает очень медленно.)

mvn findbugs:check

Если все тесты пройдены, добавьте изменение в индекс (область подготовки Git):

git add .

Убедитесь, что все добавленные, измененные или удаленные файлы отражены в индексе.

git status

В выходных данных git status найдите раздел Changes to be committed (Изменения, которые будут зафиксированы).

Начинаю код-ревью

Когда все будет готово к проверке, создайте новую проблему на сайте 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. Сохраните файл diff на локальном компьютере, например под именем issue123456.diff.
  5. Перейдите в локальное рабочее дерево Git и примените diff с помощью команды patch:
patch -p1 < issue123456.diff

Чтобы убедиться, что вы импортировали правильный diff-файл, выполните команду git diff в рабочем дереве.

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

Чтобы запустить тесты и установить пакет, используйте следующую команду:

mvn clean install checkstyle:check

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

В целом, код не может быть отправлен в репозиторий GitHub, пока рецензент кода не убедится, что код готов. В этот момент принято отвечать сообщением "LGTM" (Looks Good To Me).

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

Важно! Перед фиксацией кода перенесите последние изменения в рабочее дерево и обновите его до последней фиксации из репозитория 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" в левом верхнем углу перед идентификатором.

Отмена набора изменений

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

git checkout -- .