Cómo crear una solicitud de extracción en GitHub

Introducción

Git es un sistema de control de versiones distribuido de código abierto que facilita la gestión de proyectos de software colaborativo. Muchos proyectos almacenan sus archivos en un repositorio Git, y plataformas como GitHub han hecho que compartir código y contribuir sea accesible, valioso y eficaz.

Los proyectos de código abierto alojados en repositorios públicos se benefician de las contribuciones de la comunidad de desarrolladores más amplia a través de solicitudes de extracción, que solicitan que el proyecto acepte los cambios que ha realizado en su repositorio de código.

Este tutorial lo guiará a través de cómo realizar una solicitud de extracción a un repositorio Git a través de la línea de comandos para que pueda contribuir a proyectos de software de código abierto.

Requisitos previos

Debe tener Git instalado en su equipo local. Esta guía le ayudará a comprobar si Git está instalado en su ordenador y le guiará en el proceso de instalación para su sistema operativo.

También necesitarás tener o crear una cuenta de GitHub. Puedes hacerlo a través del sitio web de GitHub, github.com, e iniciar sesión o crear tu cuenta.

A partir de noviembre de 2020, GitHub eliminó la autenticación con contraseña. Por este motivo, para acceder a los repositorios de GitHub mediante la línea de comandos, deberá crear un token de acceso personal o agregar la información de su clave pública SSH.

Finalmente, necesitas identificar un proyecto de software de código abierto al que contribuir. Puedes aprender más sobre proyectos de código abierto leyendo esta introducción.

Crear una copia del Repositorio

Un repositorio, o repo para abreviar, es esencialmente el directorio raíz de un proyecto. El repositorio contiene todos los archivos relevantes del proyecto, incluyendo la documentación, y también almacena el historial de edición de cada archivo. En GitHub, los repositorios pueden tener múltiples colaboradores y pueden ser públicos o privados.

Para trabajar en un proyecto de código abierto, primero necesitas obtener tu propia copia del repositorio. Para ello, debes bifurcar el repositorio y luego clonarlo para tener una copia de trabajo local.

Bifurcar el repositorio

Puedes crear un repositorio en GitHub navegando en tu navegador a la URL de GitHub del proyecto de código abierto al que deseas contribuir.

Las URL de los repositorios de GitHub se refieren tanto al nombre de usuario asociado con el propietario del repositorio como al nombre del mismo. Por ejemplo, la Comunidad DigitalOcean (nombre de usuario: do-community) es propietaria del repositorio del proyecto cloud_haiku, por lo que la URL de GitHub para ese proyecto es:

https://github.com/do-community/cloud_haiku

En el ejemplo anterior, do-community es el nombre de usuario y cloud_haiku es el nombre del repositorio.

Una vez que hayas identificado el proyecto al que quieres contribuir, puedes navegar a la URL, que tiene el siguiente formato:

https://github.com/username/repository

O puedes buscar el proyecto utilizando la barra de búsqueda de GitHub.

Cuando esté en la página de inicio del repositorio, aparecerá un botón Bifurcar en la parte superior derecha de la página, debajo de su ícono de usuario:

Haz clic en el botón Bifurcar para iniciar el proceso. Recibirás una notificación en la ventana de tu navegador indicando que el repositorio que estás bifurcando está siendo procesado.

Una vez completado el proceso, su navegador irá a una página similar a la página del repositorio anterior, excepto que en la parte superior verá su nombre de usuario antes del nombre del repositorio, y en la URL también verá su nombre de usuario antes del nombre del repositorio.

Entonces, en el ejemplo anterior, en lugar de do-community/cloud_haiku en la parte superior de la página, verá su nombre de usuario/cloud_haiku y la nueva URL se verá así:

https://github.com/your-username/cloud_haiku

Con el repositorio bifurcado, estás listo para clonarlo para tener una copia local del código base.

Simular el repositorio

Para crear su propia copia local del repositorio al que desea contribuir, primero abriremos una ventana de terminal.

Usamos el comando git clone junto con una URL que apunta a la bifurcación de su repositorio.

Esta URL será la misma que la anterior, excepto que ahora termina en .git. En el ejemplo de cloud_haiku, la URL sería algo así, con tu nombre de usuario reemplazado por tu nombre de usuario real:

https://github.com/your-username/cloud_haiku.git

También puedes copiar la URL usando el botón verde "⤓ Código" desde la página del repositorio que separaste de la página principal. Después de hacer clic en el botón, puedes copiar la URL haciendo clic en el botón del portapapeles junto a la URL:

Una vez que tenemos la URL, estamos listos para clonar el repositorio. Para ello, combinamos el comando git clone con la URL del repositorio desde la línea de comandos en una ventana de terminal:

git clone https://github.com/your-username/repository.git

Crear una nueva rama

Al trabajar en un proyecto colaborativo, tú y otros desarrolladores que contribuyen al repositorio tendrán ideas diferentes para nuevas funciones o correcciones al mismo tiempo. Algunas de estas nuevas funciones no tardarán mucho en implementarse, pero otras sí. Por esta razón, es importante ramificar el repositorio para gestionar el flujo de trabajo, aislar el código y controlar qué funciones se retornarán a la rama principal del repositorio del proyecto.

La rama inicial de un repositorio de proyecto suele denominarse rama maestra. Se recomienda considerar que todo en la rama maestra es implementable para que otros puedan usarlo en cualquier momento.

Nota: En junio de 2020, GitHub actualizó su terminología para referirse a las ramas de código fuente predeterminadas como ramas maestras, en lugar de ramas maestras. Si tu rama predeterminada aún aparece como maestra, puedes cambiarla a maestra modificando su configuración.

Al crear una rama basada en un proyecto existente, debe crearla a partir de la rama principal. Asegúrese también de que el nombre de la rama sea descriptivo. En lugar de llamarla "mi-rama", utilice un nombre como frontend-hook-migration o fix-documentation-type.

Para crear una rama desde nuestra ventana de terminal, cambiamos nuestro directorio para trabajar en el directorio del repositorio. Asegúrate de usar el nombre real del repositorio (como cloud_haiku) para cambiar a ese directorio.

cd repository

Ahora, crearemos nuestra nueva rama con el comando git branch. Asegúrate de darle un nombre descriptivo para que quienes trabajen en el proyecto sepan en qué estás trabajando.

git branch new-branch

Ahora que se ha creado nuestra nueva rama, podemos trabajar en ella usando el comando git checkout:

git checkout new-branch

Después de ingresar el comando git checkout, recibirá el siguiente resultado:

Output
Switched to branch 'new-branch'

Alternativamente, puede comprimir los dos comandos anteriores creando y cambiando a una nueva rama, con el siguiente comando y el indicador -b:

git checkout -b new-branch

Si desea volver al estado original, utilice el comando checkout con el nombre de la rama original:

git checkout main

El pago le permite cambiar entre múltiples ramas, para que pueda trabajar en múltiples funciones al mismo tiempo.

En este punto, ahora puedes modificar archivos existentes o agregar nuevos archivos al proyecto en tu rama.

Realizar cambios a nivel local

Para demostrar la creación de una solicitud de extracción, usaremos el ejemplo del repositorio cloud_haiku y crearemos un nuevo archivo en nuestra copia local. Usa tu editor de texto favorito para crear un nuevo archivo y así poder añadir un nuevo poema haiku, como se explica en las instrucciones de ayuda. Por ejemplo, podemos usar nano y llamar a nuestro archivo de ejemplo filename.md. Debes llamar a tu archivo por su nombre original con la extensión md. para Markdown.

nano filename.md

A continuación, añadiremos texto al nuevo archivo, siguiendo las instrucciones de ayuda. Usaremos la plantilla de Jekyll y añadiremos un haiku con líneas discontinuas. El archivo a continuación es un ejemplo, ya que deberá proporcionar un haiku original.

---
layout: haiku
title: Octopus Cloud
author: Sammy
---
Distributed cloud <br>
Like the octopuses' minds <br>
Across the network <br>

Una vez ingresado el texto, guarde y cierre el archivo. Si usa nano, presione CTRL + X, luego Y y luego ENTER.

Una vez que hayas modificado un archivo existente o añadido uno nuevo al proyecto elegido, puedes almacenarlo en tu repositorio local. Esto se hace con el comando git add. En nuestro ejemplo, filename.md, escribiríamos el siguiente comando.

git add filename.md 

Pasamos el nombre del archivo que creamos a este comando para almacenarlo en nuestro repositorio local. Esto garantiza que el archivo esté listo para agregarse.

Si desea agregar todos los archivos que ha modificado a un directorio específico, puede organizarlos todos con el siguiente comando:

git add .

Aquí el punto o puntita agrega todos los archivos relevantes.

Si desea agregar de forma recursiva todos los cambios, incluidos los cambios en los subdirectorios, puede escribir:

git add -A

O bien, puede escribir git add -all para preparar todos los archivos nuevos.

Al preparar nuestro archivo, queremos confirmar los cambios que hicimos en el repositorio con el comando git commit.

Realizar cambios

El mensaje de confirmación es un aspecto importante de tu contribución al código. Ayuda a los mantenedores y a otros colaboradores a comprender plenamente el cambio realizado, su razón de ser y su importancia. Además, los mensajes de confirmación proporcionan un registro histórico de los cambios en el proyecto en su conjunto, lo que ayuda a los futuros colaboradores en el proceso.

Si tenemos un mensaje muy corto, podemos capturarlo con el indicador -m y el mensaje entre comillas. En nuestro ejemplo de añadir un haiku, nuestra confirmación de Git podría verse así.

git commit -m "Added a new haiku in filename.md file"

A menos que se trate de un cambio menor o esperado, podríamos añadir un mensaje de confirmación más largo para que nuestros colaboradores estén completamente informados de nuestra contribución. Para registrar este mensaje más largo, ejecutamos el comando git commit, que abre el editor de texto predeterminado:

git commit

Al ejecutar este comando, es posible que se encuentre en el editor vim, del cual puede salir escribiendo :q. Si desea configurar su editor de texto predeterminado, puede hacerlo con el comando git config y establecer nano como editor predeterminado, por ejemplo:

git config --global core.editor "nano"

o vim:

git config --global core.editor "vim"

Después de ejecutar el comando git commit, dependiendo del editor de texto predeterminado que estés usando, tu ventana de terminal debería mostrar un documento para que lo edites, que se verá así:

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch new-branch
# Your branch is up-to-date with 'origin/new-branch'.
# Changes to be committed:
# modified: new-feature.py

Debajo de los comentarios introductorios, debes agregar el mensaje de confirmación al archivo de texto.

Para escribir un mensaje de confirmación útil, debes incluir un resumen en la primera línea, de unos 50 caracteres. En esta sección, dividida en secciones fáciles de entender, debes agregar una explicación que explique el motivo del cambio, el funcionamiento del código e información adicional que lo explique a quienes revisarán el trabajo durante la fusión. Intenta ser lo más servicial y proactivo posible para asegurarte de que quienes mantienen el proyecto comprendan plenamente tu contribución.

Impulsando cambios

Una vez que hayas guardado y salido del archivo de texto del mensaje de confirmación, puedes verificar qué confirmó Git con el siguiente comando:

git status

Dependiendo de los cambios que realices, obtendrás un resultado similar al siguiente:

Output
On branch new-branch
nothing to commit, working tree clean

En este punto, puedes usar el comando git push para aplicar los cambios a la rama actual de tu repositorio bifurcado:

git push --set-upstream origin new-branch

Este comando le proporcionará una salida para informarle del progreso y será similar al siguiente:

Output
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 336 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://github.com/your-username/repository.git
a1f29a6..79c0e80 new-branch -> new-branch
Branch new-branch set up to track remote branch new-branch from origin.

Ahora puedes ir al repositorio bifurcado en tu página web de GitHub y navegar a la rama que enviaste para ver los cambios que realizaste en el navegador.

En este punto, es posible solicitar una extracción al repositorio principal, pero si aún no lo ha hecho, debe asegurarse de que su repositorio local esté actualizado con el repositorio ascendente.

Actualización del repositorio local

Mientras trabajas en un proyecto con otros colaboradores, necesitas mantener tu repositorio local actualizado, ya que no querrás enviar una solicitud de extracción de código que automáticamente cause conflictos (aunque en proyectos de código compartido, es inevitable que ocurran). Para mantener tu versión local del código base actualizada, necesitas sincronizar los cambios.

Primero, configuraremos un control remoto para la horquilla y luego sincronizaremos la horquilla.

Configurar un control remoto para la horquilla

Los repositorios remotos te permiten colaborar con otros en un proyecto Git. Cada repositorio remoto es una versión del proyecto alojada en Internet o en una red a la que tienes acceso. Según tus privilegios de usuario, cada repositorio remoto debería estar disponible como de solo lectura o de lectura y escritura.

Para sincronizar los cambios que realices en una bifurcación con el repositorio principal con el que trabajas, necesitas configurar un control remoto que apunte al repositorio original. Solo necesitas configurar el control remoto una vez en el repositorio original.

Primero, revisemos qué repositorios remotos has configurado. El comando git remote listará todos los repositorios remotos que hayas especificado previamente, así que si clonas tu repositorio como hicimos anteriormente, al menos obtendrás la salida del repositorio de origen, que es el nombre predeterminado de Git para el directorio clonado.

Desde el directorio del repositorio en nuestra ventana de terminal, usemos el comando git remote con el indicador -v para mostrar las URL que Git ha almacenado junto con sus nombres cortos remotos correspondientes (como "origen"):

git remote -v

Dado que simulamos un repositorio, nuestro resultado debería verse similar a esto:

Output
origin https://github.com/your-username/forked-repository.git (fetch)
origin https://github.com/your-username/forked-repository.git (push)

Si ya ha configurado más de un control remoto, el comando git remote -v los enumerará todos.

A continuación, especificamos un nuevo repositorio remoto para sincronizar con la bifurcación. Este será el repositorio original del que nos bifurcamos. Para ello, usaremos el comando git remote add.

git remote add upstream https://github.com/original-owner-username/original-repository.git

Para nuestro ejemplo de cloud_haiku, este comando sería el siguiente:

git remote add upstream https://github.com/do-community/cloud_haiku.git

En este ejemplo, upstream es el nombre corto que proporcionamos para el repositorio remoto, ya que, en términos de Git, "upstream" se refiere al repositorio desde el que clonamos. Si queremos añadir un puntero remoto al repositorio de un colaborador, podríamos proporcionar su nombre de usuario o un alias abreviado para el nombre corto.

Usando nuevamente el comando git remote -v desde el directorio del repositorio, podemos verificar que nuestro puntero remoto se ha agregado correctamente al repositorio ascendente:

git remote -v

Output
origin https://github.com/your-username/forked-repository.git (fetch)
origin https://github.com/your-username/forked-repository.git (push)
upstream https://github.com/original-owner-username/original-repository.git (fetch)
upstream https://github.com/original-owner-username/original-repository.git (push)

Ahora puedes hacer referencia a upstream en la línea de comando en lugar de escribir la URL completa y estás listo para sincronizar tu bifurcación con el repositorio principal.

Sincronizar la horquilla

Una vez que hemos configurado un control remoto que hace referencia al repositorio principal y ascendente en GitHub, estamos listos para sincronizar nuestra bifurcación del repositorio para mantenerlo actualizado.

Para sincronizar nuestra bifurcación, desde el directorio del repositorio local en una ventana de terminal, usamos el comando git fetch para obtener las ramas junto con sus correspondientes commits del repositorio original. Dado que usamos el nombre corto "upstream" para referirnos al repositorio original, lo pasamos al comando.

git fetch upstream

Dependiendo de la cantidad de cambios realizados desde la bifurcación del repositorio, el resultado puede variar e incluir varias líneas contando, comprimiendo y descomprimiendo objetos. El resultado final será similar a las líneas a continuación, pero puede variar según la cantidad de ramas del proyecto:

Output
From https://github.com/original-owner-username/original-repository
* [new branch] main -> upstream/main

Ahora, las confirmaciones en la rama principal se almacenan en una rama local llamada upstream/main.

Vayamos a la rama maestra local de nuestro repositorio:

git checkout main

Output
Switched to branch 'main'

Ahora fusionamos cualquier cambio realizado en la rama principal del repositorio principal, al que tendremos acceso a través de nuestra rama principal/upstream local, en nuestra rama maestra local:

git merge upstream/main

La salida aquí será diferente, pero comenzará con una actualización si se han realizado cambios o si ya está actualizado. Si no se han realizado cambios desde que se bifurcó el repositorio.

La rama maestra de tu bifurcación ahora está sincronizada con el repositorio ascendente y los cambios locales que realizaste no se pierden.

Dependiendo de tu flujo de trabajo y del tiempo que dediques a realizar cambios, puedes sincronizar tu bifurcación con el código original en el repositorio principal con la frecuencia que consideres conveniente. Sin embargo, es fundamental sincronizar tu bifurcación justo antes de realizar una solicitud de incorporación de cambios para asegurarte de no enviar automáticamente código conflictivo.

Solicitud de extracción

En este punto, estás listo para enviar una solicitud de extracción al repositorio principal.

Debes ir a tu repositorio de bifurcación y presionar el botón de nueva solicitud de extracción en el lado izquierdo de la pantalla.

En la página siguiente, puede cambiar la rama. En cada lado, puede seleccionar el repositorio y la rama correspondientes en el menú desplegable.

Por ejemplo, al seleccionar la rama principal del repositorio a la izquierda y la nueva rama bifurcada a la derecha, debería aparecer una pantalla indicando que las ramas se pueden fusionar. Si no hay código que compita:

Debes agregar un título y un comentario a los campos correspondientes y luego presionar el botón Crear solicitud de extracción.

En este punto, los responsables del repositorio principal decidirán si aceptan o no tu solicitud de extracción. Es posible que te pidan que edites o corrijas tu código mediante una revisión de código antes de aceptar la solicitud.

Resultado

En este punto, has enviado correctamente una solicitud de extracción a un repositorio de software de código abierto. Después, asegúrate de actualizar y modificar tu código mientras esperas su revisión. Los encargados del proyecto podrían pedirte que modifiques tu código, así que prepárate para ello.

Participar en proyectos de código abierto y convertirse en un desarrollador activo puede ser una experiencia gratificante. Contribuir regularmente al software que usas con frecuencia te permite asegurar que sea lo más valioso posible para otros usuarios finales.