Cómo contribuir

Contratos de Licencia para Colaboradores (CLA)

Antes de que podamos aceptar tus parches de código, debes enviar un Contrato 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 el propietario de la propiedad intelectual, envía un CLC individual.
  • Si trabajas para una empresa, esta debe presentar un CLC corporativo a fin de 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 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. 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 a un problema (un informe de errores o una solicitud de función) en nuestra Herramienta de seguimiento de errores de GitHub. Si aún no hay ninguno, 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 del código. A continuación, se proporcionan instrucciones detalladas para todos estos procesos.
  6. Una vez que se revise tu código y recibas la aprobación, confírmalo. Si no eres un colaborador oficial, este lleva tu conjunto de cambios al repositorio oficial.

Utilizamos las siguientes herramientas y procesos:

  • Usamos Git como sistema de control de versión.
  • Usamos Maven para el sistema de compilación, así como 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" hace referencia a 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 función 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 y que Eclipse procesa automáticamente.

Cómo configurar el entorno de desarrollo

Requisitos previos

  1. Instala Java 6. Es posible que debas establecer tu variable JAVA_HOME.
  2. Instala Maven. En este documento, se presupone que tienes conocimientos básicos sobre los comandos de Maven.
  3. Opcional: Instala el SDK de Android y configura 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"

Cómo autenticar con GitHub desde Git

Para poder revisar el código desde GitHub, debes autenticarte con GitHub mediante HTTP o SSH. Antes de continuar con las instrucciones que se indican a continuación, lee las instructions de GitHub para comenzar a realizar la clonación con HTTPS o SSH. Si deseas obtener más información sobre Git en general, Pro Git es un buen recurso.

Revisa el código

Usa HTTPS

Para revisar el repositorio de la biblioteca en la rama “master” de desarrollo, ejecuta el siguiente comando:

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

Usa SSH

Para revisar el repositorio de la biblioteca en la rama “principal” de desarrollo, 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, sigue estos pasos:

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 los Servicios de Google Play

La primera vez que configures el proyecto, deberás instalar el archivo google-play-services.jar. Para ello, sigue 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 de paquetes y selecciona Extras > Google Play Services.
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

Cómo compilar 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 datos 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 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 de código

Cómo descargar 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: 

Prepara tu código para la revisión

Antes de enviar el código para su 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 el cambio pase todas las pruebas, agrégalo 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, verifica la sección llamada “Cambios que se confirmarán”.

Comienza la revisión del código

Cuando esté 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, el número de error 123456, ejecuta el siguiente comando:

upload.py --rev=HEAD -i 123456

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

Si prefieres el flujo de trabajo típico de GitHub, es probable que hayas bifurcado el repositorio de GitHub y 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 esté sincronizada con el repositorio upstream. 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 conjuntos de cambios confirmados localmente.

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, confírmalos y envíalos al repositorio remoto.

Importar un conjunto de cambios

Para detectar errores con anticipación, asegúrate de extraer los cambios más recientes del repositorio remoto al árbol de trabajo. Asegúrate de que tu á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 verificar el contenido del índice y del árbol de trabajo, haz lo siguiente:

git status

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

  1. Abre el problema en codereview.appspot.com.
  2. Para el parche en cuestión, busca "Descargar sin procesar" en la parte superior derecha de la especificación del parche.
  3. Haz clic en "raw" 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 a tu árbol de trabajo de Git local y aplica la diferencia mediante el comando patch:
patch -p1 < issue123456.diff

Para verificar si 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

Cómo aprobar 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é listo. En ese momento, la convención es responder con el mensaje "LGTM".

Confirma el código

Importante: Antes de confirmar tu código, inserta los cambios más recientes en tu árbol de trabajo y actualízalo a la confirmación más reciente del repositorio de GitHub:

git pull

Si hay algún conflicto, resuélvelo y, luego, asegúrate de hacer que todas las pruebas se vuelvan a aprobar.

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

git commit

Ingresa un mensaje como el siguiente (suponiendo que estás solucionando o implementando el problema n.o 123, que se muestra en la Herramienta de seguimiento de errores de GitHub):

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

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

  • Si se trata de una solución a un problema en la Herramienta de seguimiento de errores, incluye el número, tal 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 para darle crédito al autor del cambio márcalo 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 hay una forma conveniente de averiguar la revisión del código asociada con una confirmación, lo que es útil para mantener un historial de análisis.

Para enviar el cambio al repositorio de GitHub, sigue estos pasos:

git push

Si durante git push recibes un mensaje de error que indica que se rechazan las actualizaciones (quizás olvidaste ejecutar git pull), aquí se muestra cómo combinar los cambios más recientes y enviar tus cambios 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, 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 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, ya que literalmente borra todos los cambios locales.

git checkout -- .