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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

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

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

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

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

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

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

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

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

Если вы являетесь разработчиком 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

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

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 и выберите Window > Android SDK Manager или запустите 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 и примените diff с помощью команды 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 -- .