Cómo enviar parches

En esta página, se describe el proceso completo para enviar un parche al Proyecto de código abierto de Android (AOSP), incluidos la solicitud de revisiones y el seguimiento de cambios con Gerrit. Gerrit es un sistema de revisión de código basado en la Web para proyectos que usan Git. Este sistema fomenta el uso más centralizado de Git, ya que les permite a todos los usuarios autorizados enviar cambios, que se fusionan automáticamente si pasan la revisión de código. Además, para facilitar la revisión, Gerrit muestra los cambios uno al lado del otro en el navegador y permite que se incluyan comentarios intercalados.

Requisitos previos

Antes de comenzar, asegúrate de haber hecho lo siguiente:

Recursos

  • Consulta la página de Herramientas de control de código fuente para obtener detalles sobre Repo y Git.
  • Si deseas obtener más información sobre las diferentes funciones que se pueden desempeñar en la comunidad de Código abierto de Android, consulta la página Funciones dentro del proyecto.
  • Para obtener información sobre licencias de contribución de código en la plataforma de Android, consulta la página Licencias.

Cómo configurar Git

Para usar Gerrit, tu correo electrónico debe estar asociado con una Cuenta de Google. Ejecuta los siguientes comandos para configurar Git con el nombre y la dirección de correo electrónico asociados con una Cuenta de Google registrada:

git config --global user.name Your Name
git config --global user.email your_email@gmail.com

Autenticación con el servidor

Si compartes una dirección IP con otros usuarios, se pueden activar cuotas incluso con patrones de uso normales. Esto puede ocurrir, por ejemplo, si muchos usuarios sincronizan clientes nuevos desde la misma dirección IP en un período corto. El acceso autenticado utiliza una cuota distinta para cada usuario, sin importar la dirección IP. Si quieres obtener información para activar el acceso autenticado, consulta cómo usar la autenticación.

Cómo iniciar una rama del repositorio

Por cada cambio que intentes realizar, debes comenzar una rama nueva dentro del repositorio de Git pertinente: 

repo start NAME .

You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and isn't included either on Gerrit or in the final source tree.

Make your change

Modify the source files, and test your changes.

For any changes made, follow License header best practices.

Commit your change

Commit the changes to your local repository with these commands:

git add -A
git commit -s

Descripciones de los cambios

  • Línea 1: Encabezado

    Proporciona un resumen de una línea (50 caracteres como máximo).

    Gerrit y Git usan ese formato para varias pantallas. Es la parte más importante y densa del mensaje de confirmación. Considera usar prefijos para describir el área que modificaste y, luego, describir el cambio que hiciste en esta confirmación, como el que se muestra a continuación con el prefijo ui:

    ui: Removes deprecated widget

  • Línea 2: Espacio en blanco

    Deja esta línea siempre en blanco.

  • Línea 3: Cuerpo

    Escribe una descripción más larga que comience en esta línea.

    Debe tener un máximo de 72 caracteres. Describe qué problema resuelve el cambio y cómo lo hace. Si bien esta descripción es opcional cuando implementas funciones nuevas, será muy útil para otros colaboradores si posteriormente hacen referencia a este cambio; en especial, para las depuraciones.

    Incluye una nota breve sobre cualquier suposición o información general que pueda ser importante cuando otro colaborador trabaje en esta función.

Se agregan automáticamente al mensaje de confirmación un ID de cambio único, tu nombre y tu correo electrónico, tal como los proporcionaste durante repo init.

El siguiente es un ejemplo de mensaje de confirmación:

Line 1, Headline - a short description

Line 3, Body - Add the detailed description of your patch here. Use as many lines
as needed. You can write an overall description, then list specifics.

I6e3c64e7a:Added a new widget.
I60c539a8f:Fixed the spinning image.
To read a blog about good commit descriptions (with examples), see How to Write a Git Commit Message by Chris Beams.

Upload to Gerrit

After you commit your change to your personal history, upload it to Gerrit with this command: 

repo upload

If you started multiple branches in the same repository, you're prompted to select which ones to upload.

After a successful upload, Repo provides you with the URL of a new page on Gerrit. Click the link that Repo gives you to view your patch on the review server, add comments, or request specific reviewers for your patch.

Request a review

After you've uploaded your changes to Gerrit, the patch must be reviewed and approved by the appropriate code owners. Locate code owners in OWNERS files.

To find the appropriate code owners and add them as reviewers for your change, follow these steps.

  1. Select the SUGGEST OWNERS link in the Gerrit UI to see a list of code owners for the files in your patch.

    suggest owners link in Gerrit
    Figure 1. Suggest owners link in Gerrit

  2. Add code owners from the list as reviewers for your patch.

To determine the status of the files in your patch, check for the following icons next to the files in the patch.

  • (checkmark icon): Approved by code owner
  • (cross icon): Not approved by code owner
  • (clock icon): Pending approval by code owner
Figure 2. Example of files with icons showing code owner approval status

Upload a replacement patch

Suppose a reviewer looked at your patch and requested a small modification. You can amend your commit within Git, which results in a new patch on Gerrit that has the same change ID as the original. 

git add -A
git commit --amend

Cuando subas el parche modificado, se reemplazará el original en Gerrit y en tu historial de Git local.

Cómo resolver conflictos de sincronización

Si se envían otros parches al árbol de fuentes, y estos entran en conflicto con los tuyos, deberás reubicar tu parche sobre el HEAD nuevo del repositorio de fuentes. Para ello, ejecuta el siguiente comando: 

repo sync

El comando repo sync recupera las actualizaciones del servidor de origen y, luego, intenta reubicar automáticamente tu HEAD en el nuevo HEAD remoto.

Si no se realiza correctamente el ajuste automático, hazlo de forma manual.

repo rebase

Otra herramienta que puedes usar para resolver el conflicto de reubicación es git mergetool. Cuando hayas combinado de forma correcta los archivos en conflicto, ejecuta este comando: 

git rebase --continue

Después de terminar la reubicación automática o manual, ejecuta repo upload para enviar tu parche reubicado.

Después de la aprobación de un envío

Cuando un envío pasa por los procesos de revisión y verificación, Gerrit combina el cambio automáticamente en el repositorio público. Otros usuarios pueden ejecutar repo sync para implementar la actualización en sus respectivos clientes locales.

Para proyectos upstream

Android utiliza varios proyectos de código abierto (por ejemplo, el kernel de Linux y WebKit), como se describe en la sección Administración del software de Android. Para la mayoría de los proyectos que se encuentran en external/, realiza los cambios en sentido upstream y, luego, informa a los encargados de mantenimiento de Android acerca de la versión upstream nueva que contiene estos cambios.

También es posible que subas parches que provoquen el seguimiento de una nueva versión upsteam. Ten en cuenta que estos pueden ser cambios difíciles de realizar si el proyecto se usa mucho en Android, como la mayoría de los más grandes que se mencionan a continuación (que se suelen actualizar con cada versión nueva).

Un caso interesante es Bionic. Gran parte del código es de BSD. Por lo tanto, a menos que el cambio se realice en código nuevo de Bionic, asegúrate de crear una corrección upstream y, luego, extraer un archivo nuevo de la BSD correspondiente.

Kernel de Android

Realiza todos los cambios de manera upstream. Para obtener orientación general, sigue los lineamientos de contribución del kernel de Android y la página para desarrollar código de kernel para GKI.

ICU

Realiza todos los cambios en el proyecto de ICU en external/icu (carpetas icu4c/ y icu4j/) en la página principal de ICU-TC. Consulta Submitting ICU Bugs and Feature Requests (solo disponible en inglés) para obtener más información. Agrega la etiqueta "Android" a todas las solicitudes upstream de Jira.

CLDR

La mayoría de los datos lingüísticos de ICU provienen del proyecto CLDR de Unicode. Envía todas las solicitudes en sentido upstream como se explica en Contributing to CLDR (solo disponible en inglés) y agrega la etiqueta "Android".

LLVM/Clang/Compiler-rt

Realiza todos los cambios en los proyectos relacionados con LLVM (external/clang, external/compiler-rt, external/llvm) desde la página de Infraestructura de compiladores de LLVM.

mksh

Realiza todos los cambios en el proyecto MirBSD Korn Shell en external/mksh mediante el envío de un correo electrónico a miros-mksh en el dominio mirbsd.org (no se requiere suscripción) o a través de Launchpad.

OpenSSL

Realiza todos los cambios en el proyecto OpenSSL en external/openssl desde la página de OpenSSL.

V8

Envía todos los cambios del proyecto V8 en external/v8 desde la página de problemas de V8. Consulta Contributing to V8 (solo disponible en inglés) para obtener más información.

WebKit

Realiza todos los cambios en el proyecto WebKit en external/webkit desde la página de WebKit. Para comenzar el proceso, presenta un error de WebKit. En el error, ingresa Android en los campos Platform y OS solo si el error es específico de Android. Es más probable que un informe de errores reciba la atención de los revisores después de que se agregue una propuesta de solución y se incluyan pruebas. Consulta Contributing Code to WebKit (solo disponible en inglés) para obtener más información.

zlib

Realiza todos los cambios en el proyecto zlib en external/zlib desde la página principal de zlib.