Envía los cambios de código

En esta página, se describe el proceso completo para enviar un cambio de código al Proyecto de código abierto de Android (AOSP), incluidos la solicitud de revisiones y el seguimiento de tus cambios.

El AOSP depende de Gerrit, un sistema de revisión de código basado en la Web para proyectos que usan Git.

Firma los contratos de licencia para colaboradores

Antes de colaborar con cualquier cambio de código para AOSP, debes leer el documento de Contratos de licencia para colaboradores y encabezados, y firmar uno de los siguientes contratos:

• En calidad de colaborador individual que realiza colaboraciones en su nombre, firma el Contrato de Licencia para Colaboradores Individuales.
• En calidad de empleado que trabaja para una empresa, asegúrate de que esta haya firmado el Contrato de Licencia para Colaboradores Corporativos que te autoriza a realizar colaboraciones en nombre de la empresa.

Nota: Para hacer cambios en los proyectos upstream que usa Android, debes realizarlos directamente en el proyecto en cuestión. Para obtener más información, consulta Contribute to upstream projects.

Comienza una rama

Para cada cambio de código que intentes realizar, sigue los siguientes pasos:

1. Comienza una rama nueva dentro del repositorio de Git pertinente. Una rama no es una copia de los archivos originales, sino que funciona como puntero de una confirmación específica; por lo tanto, crear ramas locales y alternar entre ellas es una operación simple. Cuando usas ramas, puedes identificar cambios entre sí. Ejecuta este comando para comenzar una rama:

   repo start BRANCH_NAME

   Puedes iniciar varias ramas independientes al mismo tiempo en el mismo repositorio. La rama BRANCH_NAME es el directorio local de tu espacio de trabajo y no se incluye en Gerrit ni en el árbol de fuentes final. Las ramas también son específicas del proyecto en el que estás, por lo que, si necesitas cambiar archivos en diferentes proyectos como parte del mismo cambio, necesitarás una rama en cada proyecto en el que cambies archivos.

2. Verifica que se haya creado la rama nueva (opcional):

   repo status .

   Deberías ver la rama que acabas de crear. Por ejemplo:

   project frameworks/native/                      branch mynewbranch

   Nota: También puedes usar repo branches para obtener una lista de todas las ramas, en la que la rama actual (si hubiera) se muestra precedida de un asterisco (*).

Realiza y prueba el cambio

Sigue estos pasos para realizar y probar tu cambio:

1. Para asegurarte de que trabajas con la base de código más actual, sincroniza la base de código completa:

   repo sync

   Nota: Para actualizar solo el proyecto actual, agrega un punto (.) al comando repo sync: repo sync .. La sincronización del proyecto actual es más rápida que sincronizar el repositorio completo.

   Si se produce algún conflicto durante la sincronización, consulta los pasos 2-4 en Cómo resolver conflictos de sincronización.

2. Encuentra el código que quieras cambiar. Para ello, considera usar Android Code Search. Puedes usar Android Code Search para ver el código fuente de AOSP a medida que lo usas. Para obtener más información, consulta Getting started with Code Search. Para ver todo el código en la rama main dentro de Android Code Search, ve a https://cs.android.com/android/platform/superproject/main.

3. Modifica o agrega archivos fuente. Para cualquier cambio que realices, haz lo siguiente:

   • Determina si necesitas usar marcas de lanzamiento de funciones y, si es así, impleméntalas para tu código nuevo.

   • Sigue las prácticas recomendadas en Incluye los encabezados de licencia.

   • Para el código Java, sigue Estilo de código Java del AOSP para colaboradores.

   • Algunas partes del AOSP están escritas en Kotlin (.kt) y puedes usar este lenguaje en las áreas de la plataforma que ya están escritas en este. Si quieres obtener más información sobre Kotlin en Android, consulta la Guía de estilo de Kotlin y la Guía de interoperabilidad de Kotlin-Java para desarrolladores de Android. Para obtener pautas más detalladas de Kotlin, consulta el sitio del lenguaje Kotlin.

   • Cuando escribas API, sigue los Lineamientos de APIs de Android. Usa estos lineamientos para ver el contexto detrás de las decisiones de APIs de Android. Las incorporaciones y modificaciones de las APIs de la plataforma se validan con Metalava.

4. Compila Android.

5. Prueba tu compilación.

Agrega tu cambio a una etapa previa y confírmalo

Una confirmación es la unidad básica de control de revisiones en Git y consiste en un resumen de la estructura del directorio y el contenido de los archivos de todo el proyecto. Sigue estos pasos para confirmar tu cambio:

1. De forma predeterminada, Git registra los cambios que realizas, pero no hace un seguimiento de ellos. Para indicarle a Git que haga un seguimiento de los cambios, debes marcarlos o agregarlos a la etapa previa, para que luego se incluyan en una confirmación. Ejecuta este comando para agregar el cambio a una etapa previa:

   git add -A

   Este comando hace un seguimiento de los cambios que realizaste en cualquier archivo.

   Nota: Si solo quieres hacer un seguimiento de los cambios en un archivo específico, usa git add filename.
   Nota: Además de hacer un seguimiento de los cambios en archivos, git add puede utilizarse para realizar otras operaciones, como agregar modificaciones y eliminaciones de archivos en una etapa previa.

2. Agrega los archivos al área de la etapa previa y confírmalos, o bien almacénalos en tu base de datos local:

   git commit -s

   De forma predeterminada, el editor de texto se abre, se te solicita que brindes un mensaje de confirmación.

3. Brinda un mensaje de confirmación en el siguiente formato:

   • Línea 1: Encabezado. Proporciona un resumen de una línea sobre el cambio (50 caracteres como máximo). Considera usar prefijos para describir el área que modificaste y, luego, describir el cambio que hiciste en esta confirmación, como el siguiente ejemplo que incluye un cambio de la interfaz de usuario:

     ui: Removes deprecated widget
     

   • Línea 2: Línea en blanco. Después del encabezado, agrega una línea en blanco.

   • Línea 3: Cuerpo. Proporciona una descripción larga que se ajuste a un máximo de 72 caracteres. Describe qué problema resuelve el cambio y cómo lo hace. Si bien el cuerpo es opcional, es útil para otros que necesitan referirse al cambio. Asegúrate de incluir una nota breve sobre cualquier suposición o información general que pueda ser importante cuando otro colaborador trabaje en esta función.

   Si quieres leer un blog sobre descripciones de confirmaciones efectivas (con ejemplos), consulta la entrada How to Write a Git Commit Message.

4. Guarda la confirmació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.

Sube el cambio para su revisión

Después de confirmar el cambio en tu historial personal de Git, súbelo a Gerrit:

1. Ejecuta el siguiente comando para subir todas tus confirmaciones en todos tus proyectos.

   repo upload

   Todos los cambios en todos los proyectos se incluyen en la carga.

   Nota: Para subir los cambios solo en el proyecto actual, agrega un punto (.) al comando repo upload: repo upload ..
   Nota: Si trabajas en un cambio que exige cambiar archivos en varios proyectos, usa un tema en Gerrit para vincular los cambios, independientemente de si usas repo upload o repo upload .. El tema de Gerrit garantiza que los cambios se mantengan juntos a efectos de las pruebas previas al envío y a través de la autofusión. Para obtener más información, consulta Using Topics.

   Se te pedirá que ejecutes comandos del hook.

2. Presiona a y, luego, Intro.

   Se te pedirá que apruebes la carga:

   Upload project frameworks/native/ to remote branch main:
   branch BRANCH_NAME ( 1 commit, Wed Aug 7 09:32:33 2019 -0700):
          ff46b36d android codelab change
   to https://android-review.googlesource.com/ (y/N)?
   

   Nota: Si comenzaste varias ramas en el mismo repositorio, se te pedirá que selecciones cuáles quieres subir quitando el comentario de aquellas ramas en el editor de texto.

3. Presiona y y, luego, Intro para aprobar la carga.

Deberías recibir un mensaje similar a remote: SUCCESS.

Solicita una revisión

Cuando se haya subido de forma correcta, Repo te proporcionará un vínculo a tus cambios en Gerrit. Haz clic en el vínculo para ver tus cambios en el servidor de revisión, agregar comentarios o solicitar revisiones específicos para tu cambio. Todos los cambios de código deben ser revisados por los propietarios de código pertinentes.

Nota: Las configuraciones de lanzamiento incluidas en AOSP son definidas por Google. Google no acepta contribuciones para actualizar o cambiar las marcas de lanzamiento de funciones de una configuración. En su lugar, puedes definir tus propias configuraciones de lanzamiento personalizadas, incluidos valores de marcas predeterminados en tus bifurcaciones de AOSP. Para obtener más información sobre las configuraciones de lanzamiento, consulta Cómo establecer valores de marcas de lanzamiento de funciones.

Para solicitar una revisión, haz lo siguiente:

1. En Gerrit, haz clic en SUGGEST OWNERS:

   

   Figura 1: Vínculo de sugerencia de propietarios en Gerrit

   Aparecerá el diálogo del revisor. En este, se incluye una lista de los propietarios de código que pueden revisar tu cambio.

2. Haz clic en uno para agregarlo a tu revisión.

   Nota: Para comprender cómo se determinan los propietarios, consulta el backend de búsqueda de propietarios.

   Se activa el botón SEND.

3. Escribe la dirección de correo electrónico de cualquier otra persona que desees que revise tu cambio (opcional)

4. Haz clic en +1 junto a "Autosubmit" para enviar automáticamente el cambio después de que lo aprueben (opcional). Si no haces clic en este botón, un empleado de Google tiene que enviar el cambio por ti.

5. Haz clic en SEND para enviar el cambio para su revisión.

Los propietarios de código revisan tus cambios de código y te envían comentarios para resolverlos o aprobarlos.

Determina el estado del cambio

Para determinar el estado de los archivos en tu cambio, verifica los siguientes íconos junto a ellos:

• (ícono de marca de verificación): Aprobado por el propietario de código
• (ícono de cruz): No aprobado por el propietario de código
• (ícono de reloj): Aprobación pendiente por el propietario de código

En la siguiente figura, se muestran los íconos de estado aplicados en los archivos de un cambio:

Figura 2: Ejemplo de archivos con íconos que muestran el estado de aprobación del propietario de código

Resuelve los comentarios y sube un cambio de reemplazo

Si un revisor solicita una modificación de tu actualización, puedes modificar tu confirmación dentro de Git, lo que genera en un nuevo conjunto de parches en el mismo cambio.

Nota: Si creaste otras ramas e hiciste otras confirmaciones después de subir un cambio, es probable que estés trabajando en la rama de una de esas confirmaciones y no en la rama del cambio original. Por lo tanto, antes de que puedas resolver los comentarios para la rama original, debes ir a esa rama con el comando repo start EXISTING_BRANCH_NAME.

Para resolver el comentario y modificar tu cambio, haz lo siguiente:

1. Sigue los pasos 2-4 en Realiza y prueba el cambio.

2. Ejecuta los siguientes comandos para modificar tu cambio:

   git add -A
   git commit --amend

3. Sube el cambio.

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

Resuelve los conflictos de sincronización

Si se envían otros cambios al árbol de fuentes, que entran en conflicto con los tuyos, deberás recibir un mensaje sobre estos conflictos. Para resolverlos, haz lo siguiente:

1. Para asegurarte de que trabajas con el código más actual, sigue estos pasos:

   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.

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

   repo rebase .

3. Resuelve los conflictos de fusión. Si no tienes un método preferido para resolver conflictos de fusión, puedes usar git mergetool para arreglar, de forma manual, los conflictos entre archivos.

4. Cuando hayas arreglado, de forma correcta, los archivos en conflicto, ejecuta este comando para aplicar las nuevas confirmaciones:

   git rebase --continue

Envía el cambio

Cuando un envío pasa por los procesos de revisión y verificación, un usuario opinador de Google debe enviar el código en tu lugar. Otros usuarios pueden ejecutar repo sync para implementar la actualización en sus respectivos clientes locales.

Después de que se fusiona tu envío, puedes visitar el panel de integración continua de Android para supervisar cuando los envíos se integren al árbol.