Cómo contribuir

Contratos de Licencia para Colaboradores (CLC)

Antes de que podamos aceptar tus parches de código, debes enviar una solicitud o un Contrato de Licencia para Colaboradores (CLC):

  • Si eres una persona que escribe código fuente original y tienes la certeza de que que eres el propietario de la propiedad intelectual, envía una CLC individual.
  • Si trabajas para una empresa, esta debe presentar un CLC corporativo. para indicar que puedes contribuir con tu trabajo a esta biblioteca cliente.

Sigue cualquiera de los dos vínculos anteriores para acceder al CLA adecuado y a las instrucciones sobre cómo firmarlo y enviarlo. Una vez que lo recibamos, podremos agregarte. a la lista oficial de colaboradores.

Descripción general del envío de parches

Para aportar código a este proyecto, sigue estos pasos generales:

  1. Firmar un Contrato de Licencia para Colaboradores, tal como se describió anteriormente.
  2. Únete a nuestro grupo de discusión.
  3. Configura tu entorno de desarrollo.
  4. Asocia cada uno de tus conjuntos de cambios con un problema (un informe de errores o una función solicitud) en nuestra Herramienta de seguimiento de errores de GitHub. Si aún no hay uno, crea uno nuevo y asígnalo a ti mismo.
  5. Verifica el código, crea un problema nuevo en codereview.appspot.com y completa el proceso de revisión de código. A continuación, se proporcionan instrucciones detalladas para todos estos procesos.
  6. Después de que se revise tu código y recibas la aprobación, confírmalo. Si no eres un colaborador oficial, este extraerá tu conjunto de cambios en el repositorio oficial.

Utilizamos los siguientes procesos y herramientas:

  • Usamos Git como nuestro sistema de control de versión.
  • Usamos Maven para el sistema de compilación, además de un sistema de distribución binaria.
  • Usamos codereview.appspot.com para el código las revisiones por pares. (Ten en cuenta que en la herramienta codereview.appspot.com, el término "issue" se refiere a una solicitud de revisión de código, mientras que, en la Herramienta de seguimiento de errores de GitHub, es un “problema” es un solicitud de función o informe de errores).

Si eres desarrollador de Eclipse, usa el formato de código específico del proyecto. especificadas en el directorio .settings que Eclipse procesa automáticamente.

Configura el entorno de desarrollo

Requisitos previos

  1. Instala Java 6. Es posible que debas configurar tu JAVA_HOME de salida.
  2. Instala Maven. (Este documento supone que tienes conocimientos básicos sobre los comandos de Maven).
  3. Opcional: Instala el SDK de Android y establece la variable ANDROID_HOME en la ubicación de instalación de Android.
  4. Instala Git.

Configura Git

Usa el comando git config para establecer tu nombre visible y dirección de correo electrónico predeterminados:

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

Autentica con GitHub desde Git

Para poder extraer el código de GitHub, debes autenticarte con GitHub con HTTP o SSH. Antes de continuar con la a continuación, lee el repositorio de GitHub instrucciones sobre cómo obtener debes comenzar con la clonación HTTPS o SSH. Si quieres obtener más información sobre Git en En general, Pro Git es un buen recurso.

Consulta el código

Usa HTTPS

Para consultar el repositorio de la biblioteca en la "instancia principal" de desarrollo, haz lo siguiente: rama, Ejecuta el siguiente comando:

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

Usa SSH

Para consultar el repositorio de la biblioteca en la "instancia principal" de desarrollo, haz lo siguiente: rama, marca por supuesto tienes acceso de escritura al repositorio de GitHub y, luego, ejecuta el siguiente comando:

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

Para cambiar a una rama alternativa, por ejemplo 1.12, haz lo siguiente:

git checkout --track origin/1.12

Para volver a la rama principal:

git checkout master

Para incorporar los cambios más recientes del repositorio de GitHub y actualizar tu árbol de trabajo con la última confirmación:

git pull

Maven

Instala los Servicios de Google Play

La primera vez que configures el proyecto, deberás instalar el google-play-services.jar. Para ello, sigue estos pasos:

  1. Inicia Eclipse y selecciona Ventana > Android SDK Manager o ejecuta android en la línea de comandos.
  2. Desplázate hasta el final de la lista del paquete y selecciona Extras > Google Play Google Cloud.
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

Compila el proyecto

mvn clean install

Maven instala los objetos binarios compilados en un repositorio local (por ejemplo, ~/.m2/repository). Busca objetos binarios en ese repositorio antes de recuperar desde el repositorio central de Maven.

Nota: Esta biblioteca depende de google-http-java-client y google-oauth-java-client. Cuando trabajes en una versión nueva de las tres bibliotecas que aún no se lanzaron en Maven Central, debes compilarlos en el siguiente orden:

  1. google-http-java-client
  2. google-oauth-java-client
  3. google-api-java-client Compilar en este orden garantiza que Maven recoja los binarios compilados para compilación de bibliotecas dependientes.

Proceso de revisión de código

Descarga la secuencia de comandos upload.py

Descarga la secuencia de comandos upload.py y, de manera opcional, agregarla a tu ruta de acceso.

La primera vez que ejecutes upload.py, se te solicitará un contraseña específica de la aplicación:

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

Cómo preparar tu código para la revisión

Antes de enviar el código a revisión, debes ejecutar Clirr para detectar hacia atrás. problemas de compatibilidad en tu código. Si se informan errores, debes los corriges o actualiza el archivo clirr-ignored-sensitives.xml.

mvn -q clirr:check

También debes ejecutar la herramienta FindBugs para detectar errores en el código. Si hay algún error debes corregir los errores o actualizar el archivo findbugs- exclude.xml . (ten en cuenta que FindBugs es muy lento).

mvn findbugs:check

Cuando el cambio pase todas las pruebas, agrégalo al índice (el archivo esta área):

git add .

Vuelve a comprobar que se vean reflejados todos los archivos que agregaste, modificaste o borraste. en el índice:

git status

En el resultado de git status, verifica la sección llamada “Changes to be commit” (Cambios que se confirmarán).

Comienza la revisión de código

Cuando esté todo listo para la revisión, crea un problema nuevo en codereview.appspot.com: 

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

Después de realizar más cambios, habilita a etapa los cambios nuevos. Para subir un parche nuevo, por ejemplo, para el número de emisión 123456, ejecuta el siguiente comando: 

upload.py --rev=HEAD -i 123456

Para obtener más opciones, ejecuta upload.py --help.

Si prefieres la plataforma de GitHub flujo de trabajo, es probable que hayas bifurcado en un repositorio de GitHub y creaste una rama para esta nueva función o corrección de errores. Cuando enviar código revisa las solicitudes de tu propia bifurcación, asegúrate de que la bifurcación esté sincronizada con el repositorio upstream. Para obtener más información, consulta el Centro de ayuda de GitHub sobre cómo sincronizar una bifurcación.

También puedes usar upload.py para los conjuntos de cambios confirmados de forma local.

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

Revisor de código

Si eres revisor de código, importa y prueba conjuntos de cambios antes de aprobarlos y, luego, confirmar y enviar los conjuntos de cambios al repositorio remoto.

Importa un conjunto de cambios

Para detectar errores con anticipación, asegúrate de extraer los cambios más recientes del control remoto. en tu árbol de trabajo. Asegúrate de que el árbol de trabajo esté limpio y tu índice está vacío.

Para extraer y combinar las confirmaciones más recientes del repositorio remoto, haz lo siguiente:

git pull

Para comprobar qué hay en el árbol y el índice de trabajo, haz lo siguiente:

git status

Para importar un parche a tu clon de Git local, haz lo siguiente:

  1. Abre el problema en codereview.appspot.com.
  2. Busca el parche en cuestión "Descargar sin procesar". en la parte superior derecha del la especificación del parche.
  3. Hacer clic en "sin procesar" para obtener una URL del archivo que se importará.
  4. Guarda el archivo de diferencias sin procesar en tu máquina local con un nombre como problema123456.diff.
  5. Ve a tu árbol de trabajo de Git local y aplica la diferencia con patch. :
patch -p1 < issue123456.diff

Para verificar si importaste la diferencia correcta, realiza un git diff. en tu árbol de trabajo.

Prueba el conjunto de cambios

Para ejecutar las pruebas y la instalación, usa el siguiente comando:

mvn clean install checkstyle:check

Aprueba un conjunto de cambios en codereview.appspot.com

En general, el código no se puede enviar al repositorio de GitHub hasta que el revisor de código esté satisfecho de que el código está listo. En ese punto, la convención es responder con el mensaje "LGTM". (Se ve bien para mí).

Confirma el código

Importante: Antes de confirmar el código, extrae los cambios más recientes a tu Árbol de trabajo y actualízalo a la confirmación más reciente desde GitHub siguiente:

git pull

Si hay algún conflicto, resuélvelo y asegúrate de completar todas las pruebas para nuevamente.

Para confirmar el código de forma local, haz lo siguiente: 

git commit

Ingresa un mensaje como el siguiente (suponiendo que lo estés corrigiendo o implementando Problema n.o 123, como aparece en el GitHub Herramienta de seguimiento de errores):

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

Antes de los primeros dos puntos y la descripción:

  • Si esto soluciona un problema en la Herramienta de seguimiento de errores, incluye el número de problema, como se muestra.
  • Si se trata de un cambio para una rama en particular, incluye el número de sucursal.
  • Serás el committer de esta confirmación, pero debes dar crédito a la autor del cambio marcándolo como author (--author=<author>).

Después de la descripción, incluye siempre un vínculo al problema en la revisión de código. . Este vínculo es importante porque sin él no hay una forma conveniente de averiguar la revisión de código asociada con una confirmación, que es útil para llevar un historial de la conversación.

Para enviar el cambio al repositorio de GitHub, haz lo siguiente:

git push

Si, durante git push, recibes un mensaje de error que indica que se rechazaron las actualizaciones (quizás te olvidaste de ejecutar git pull), a continuación, te mostramos cómo hacer la combinación con los cambios más recientes y envía los cambios al repositorio remoto: 

git pull
git commit
git push

Cómo resolver el problema

Asegúrate de solucionar el problema en la herramienta de revisión de código. Para ello, sigue estos pasos:

  1. Selecciona el problema en codereview.appspot.com.
  2. Haz clic en la "X". que se encuentra en la parte superior izquierda, antes de “Id”.

Cómo quitar la aplicación de parches a un conjunto de cambios

Si por alguna razón decides no confirmar un conjunto de cambios que importaste, usa el siguiente comando para eliminarlo. Ten cuidado: Literalmente borra todos los cambios locales. 

git checkout -- .