Cómo contribuir

Acuerdos de licencia para colaboradores (CLA)

Para que podamos aceptar tus parches de código, debes enviar un Acuerdo de licencia para colaboradores (CLA) individual o corporativo:

  • Si eres una persona que escribe el código fuente original y estás seguro de que eres propietario de la propiedad intelectual, envía un CLA individual.
  • Si trabajas para una empresa, esta debe enviar un CLA corporativo para indicar que estás autorizado a contribuir 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 la recibamos, podremos agregarte a la lista oficial de colaboradores.

Descripción general del envío de parches

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

  1. Firma un Acuerdo de licencia para colaboradores, 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 solicitud de función) en nuestro seguimiento de problemas de GitHub. Si aún no existe, crea un número nuevo y asígnalo.
  5. Revisa 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 revisar el código y recibir la aprobación, confirma el código. Si no es un colaborador oficial, un colaborador extraerá su conjunto de cambios al repositorio oficial.

Usamos las siguientes herramientas y procesos:

  • Usamos Git como nuestro sistema de control de versión.
  • Usamos Maven para el sistema de compilación y un sistema de distribución binaria.
  • Usamos codereview.appspot.com para las revisiones de código. (Sin embargo, ten en cuenta que en la herramienta codereview.appspot.com, el término "problema" significa una solicitud de revisión de código, mientras que en la Herramienta de seguimiento de errores de GitHub, un "problema" es una solicitud de funciones o un informe de errores).

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

Configura el entorno de desarrollo

Requisitos previos

  1. Instala Java 6. Es posible que debas configurar la variable JAVA_HOME.
  2. Instala Maven. En este documento, se supone que estás familiarizado con los comandos de Maven.
  3. Opcional: Instala el SDK de Android y establece la variable ANDROID_HOME en la ubicación de instalación para 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 consultar el código desde GitHub, debes autenticarte con GitHub mediante HTTP o SSH. Antes de continuar con las instrucciones a continuación, lee las instrucciones de GitHub para comenzar a usar la clonación HTTPS o SSH. Si quieres obtener más información sobre Git en general, Pro Git es un buen recurso.

Cómo revisar el código

Usa HTTPS

Para ver el repositorio de la biblioteca en la rama de &desarrollo principal, ejecuta el siguiente comando:

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

Usa SSH

Para verificar el repositorio de la biblioteca en la rama de desarrollo “principal”, asegúrate de tener 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:

git checkout --track origin/1.12

Para volver a la rama principal, haz lo siguiente:

git checkout master

Para extraer los últimos cambios del repositorio de GitHub y actualizar tu árbol de trabajo local a la última confirmación, haz lo siguiente:

git pull

Maven

Instala Google Play Services

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

  1. Inicia Eclipse y selecciona Window > Android SDK Manager, o ejecuta android en la línea de comandos.
  2. Desplázate hasta la parte inferior de la lista del paquete y selecciona Servicios adicionales de 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

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 recuperarlos desde el repositorio central de Maven.

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

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

Proceso de revisión del código

Descarga la secuencia de comandos upload.py

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

La primera vez que ejecutes upload.py, se te solicitará una 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 el código para su revisión

Antes de enviar el código a revisión, debes ejecutar Clirr para detectar problemas de retrocompatibilidad en tu código. Si se informan errores, debes corregirlos o actualizar el archivo clirr-ignored-differences.xml.

mvn -q clirr:check

También debes ejecutar la herramienta FindBugs para detectar errores en el código. Si se informan errores, debes corregirlos o actualizar el archivo findbugs-exclude.xml. (Ten en cuenta que FindBugs es muy lento).

mvn findbugs:check

Una vez que tu cambio pase todas las pruebas, agrega el cambio al índice (el área de etapa de pruebas de Git):

git add .

Vuelve a verificar que todos los archivos que agregaste, modificaste o borraste se reflejen en el índice:

git status

En el resultado de git status, marca la sección denominada"Cambios que se confirmarán".

Cómo iniciar la revisión de código

Cuando estés 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, organiza los cambios nuevos. Para subir un parche nuevo, por ejemplo, para emitir el número 123456, ejecuta el siguiente comando:

upload.py --rev=HEAD -i 123456

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

Si prefieres el flujo de trabajo de GitHub típico, es probable que hayas bifurcado el repositorio de GitHub y hayas creado una rama para esta nueva función o corrección de errores. Cuando envíes solicitudes de revisión de código desde tu propia bifurcación, asegúrate de que la bifurcación esté sincronizada con el repositorio ascendente. Para obtener más información, consulta la 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 un revisor de código, importa y prueba conjuntos de cambios antes de aprobarlos y, luego, confirma y envía 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 repositorio remoto a tu árbol de trabajo. Asegúrate de que el árbol de trabajo esté limpio y de que el índice esté vacío.

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

git pull

Para comprobar el índice y el árbol de trabajo, sigue estos pasos:

git status

Para importar un parche a tu clonación local de Git, sigue estos pasos:

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

Para verificar que importaste la diferencia correcta, haz una 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 con el código. En ese momento, la convención es responder con el mensaje "LGTM" (se ve bien para mí).

Confirma el código

Importante: Antes de confirmar tu código, extrae los cambios más recientes en tu árbol de trabajo y actualiza tu árbol de trabajo a la última confirmación del repositorio de GitHub:

git pull

Si hay algún conflicto, resuélvelo y, luego, asegúrate de obtener todas las pruebas para volver a aprobarlas.

Para confirmar el código de forma local, sigue estos pasos:

git commit

Ingresa un mensaje como el siguiente (suponiendo que corriges o implementas el problema n.o 123, que aparece en el Seguimiento de problemas de GitHub):

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

Antes del primer punto y la descripción:

  • Si se trata de una solución a un problema en el Registro de problemas, 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 la rama.
  • Serás el committer de esta confirmación, pero debes darle crédito al autor del cambio si lo marcas como author (--author=<author>).

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

Para enviar el cambio al repositorio de GitHub:

git push

Si, durante git push, recibes un mensaje de error que indica que se rechazaron las actualizaciones (tal vez olvidaste ejecutar git pull), sigue estos pasos para combinar los cambios más recientes y enviarlos al repositorio remoto: 

git pull
git commit
git push

Cerrando el problema

Asegúrate de cerrar el problema en la herramienta de revisión de código. Para ello, siga 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.

Quita los parches de un conjunto de cambios

Si por algún motivo decides no confirmar un conjunto de cambios que importaste, usa el siguiente comando para deshacerlo. Ten cuidado: Literalmente borra todos los cambios locales. 

git checkout -- .