Saltar al contenido principal

Configuración y Flujo de Trabajo con Forks, Ramas y Pull Requests en Git

Este documento detalla paso a paso la configuración y el flujo de trabajo utilizando forks, ramas y Pull Requests en Git, haciendo énfasis en la interacción entre tu repositorio forkeado (origin) y el repositorio original (upstream).

1. Configuración Inicial del Fork​

1.1 Realizar el Fork del Repositorio​

1.2 Clonar el Repositorio Forkeado a tu Máquina Local​

git clone cd repositorio-fork

1.3 Configurar los Remotos: Origin y Upstream​

  • Origin: Es tu repositorio forkeado (ya configurado al clonar).
  • Upstream: Es el repositorio original. Para poder traer cambios del proyecto base, agrega el remoto upstream:
git remote add upstream https://github.com/organizacion/repositorio-original.git

Verifica la configuración:

git remote -v

La salida deberá mostrar ambos remotos con sus URL correspondientes.

2. Flujo de Trabajo con Forks, Ramas y Pull Requests​

El proceso se centra en la creación y actualización de ramas, trabajando localmente y actualizando el repositorio origin, mientras que el repositorio upstream se mantiene actualizado exclusivamente mediante Pull Requests.

2.1 Creación de la Rama de Funcionalidad en Local y en Upstream​

  • Crear la rama en local:
    • Sigue la convención para nombres de rama.
  git checkout -b feat_86b44h2uw_new_payment_gateway
  • Crear la rama en Upstream:
    • Para que la rama de funcionalidad exista en upstream y origin, deberás crearla o gestionarla con el equipo.
  git push origin feat_86b44h2uw_new_payment_gateway
  git push upstream feat_86b44h2uw_new_payment_gateway

2.2 Desarrollo y Commit​

Trabaja en tu código y, una vez realizado un cambio significativo, registra el commit siguiendo la convención:

git add .
git commit -m "fix: 86b44h2uw - correct typo in payment module"

2.3 Envío del Código a Origin​

Después de realizar commits, actualiza la rama en tu repositorio origin:

git push origin feat_86b44h2uw_new_payment_gateway

Nota: La rama en upstream se actualizará mediante el Pull Request, por lo tanto no se realizan push directos a upstream desde el desarrollo diario.

2.4 Creación del Pull Request (PR)​

  1. Ingresa a la plataforma de tu repositorio y crea un PR desde la rama feat_86b44h2uw_new_payment_gateway en origin hacia la misma rama en upstream.
  2. Utiliza un título siguiendo la convención.
    • Ejemplo: docs: 86b44h2uw - update readme with installation instructions
  3. En la descripción, detalla los objetivos del PR, los cambios realizados y cualquier información adicional relevante.

3. Creación de una Rama Local a Partir de una Rama Existente en Upstream​

Cuando ya existe una rama en upstream que deseas trabajar, sigue estos pasos:

3.1 Actualizar la Información Remota​

Obtén las últimas actualizaciones de upstream:

git fetch upstream

3.2 Crear y Cambiar a la Rama Local Basada en Upstream​

Utiliza git switch para cambiar a la rama que existe en upstream. Si la rama no está creada localmente, git switch la creará automáticamente configurándola para seguir la rama remota:

git switch feat_86b44h2uw_new_payment_gateway

Explicación:
Gracias a la detección inteligente, git switch verifica si existe una rama remota con ese nombre en upstream y, de no existir localmente, la configura y crea para facilitar el seguimiento y la sincronización.

4. Actualización Directa de Ramas en Upstream a partir de Otras Ramas​

Cuando tienes dos ramas en upstream y en una de ellas necesitas incorporar los cambios de la otra, puedes hacerlo directamente desde tu entorno local sin involucrar a origin. Esto evita que en el siguiente PR se incluyan cambios no deseados.

4.1 Cambiar a la Rama que Necesita Actualización​

Por ejemplo, si la rama feat_branch_A debe recibir cambios de feat_branch_B:

git switch feat_branch_A

4.2 Integrar los Cambios desde la Otra Rama​

Realiza un pull desde feat_branch_B del repositorio upstream:

git pull upstream feat_branch_B

4.3 Pujar Directamente la Actualización a Upstream​

Una vez verificados los cambios, envía la actualización directamente a upstream:

git push upstream feat_branch_A

Consejo:
Este flujo previene que el siguiente Pull Request incluya los cambios que se tomaron de otra rama, manteniendo cada PR enfocado únicamente en la funcionalidad o corrección correspondiente.

5. Buenas Prácticas y Recomendaciones​

  • Aislamiento de Cambios:
    • Trabaja siempre en ramas dedicadas para cada funcionalidad o corrección en lugar de modificar ramas principales.
  • Mensajes Claros en Commits y PRs:
    • Utiliza convenciones consistentes para los nombres de ramas, mensajes de commit y títulos de Pull Requests. Esto facilita la trazabilidad y la revisión colaborativa.
  • Revisión y Testing:
    • Antes de generar un PR, asegúrate de que el código funcione correctamente en tu entorno local y cumpla con los estándares de calidad del proyecto.
  • Sincronización Regular:
    • Si necesitas trabajar a partir de ramas ya existentes en upstream, usa git fetch upstream y git switch para mantener tu entorno actualizado.
    • Además, cuando deba fusionarse el contenido de una rama en otra en upstream, realiza el proceso directamente en dicha rama para evitar confusiones en futuros PRs.
  • Documentación Completa:
    • Registra cualquier configuración o flujo específico que se utilice en el repositorio para que todo el equipo esté alineado en el proceso de desarrollo.