Trabajar con branches

Crea y gestiona branches de documentación para previsualizar cambios, colaborar con compañeros y fusionar actualizaciones antes de publicarlas en producción.

Las branches son una función del control de versiones que apuntan a confirmaciones específicas en tu repositorio. Tu rama de implementación, generalmente llamada main, representa el contenido que se usa para compilar tu sitio de documentación en producción. Todas las demás branches son independientes de tu sitio en producción a menos que decidas fusionarlas en tu rama de implementación.

Las branches te permiten crear instancias separadas de tu documentación para realizar cambios, obtener revisiones y probar nuevos enfoques antes de publicar. Tu equipo puede trabajar en branches para actualizar diferentes partes de tu documentación al mismo tiempo, sin afectar lo que los usuarios ven en tu sitio en producción.

El siguiente diagrama muestra un ejemplo de flujo de trabajo con branches en el que se crea una branch de funcionalidad, se realizan cambios y luego la branch de funcionalidad se fusiona en la branch principal.

Recomendamos trabajar siempre desde branches al actualizar la documentación para mantener estable tu sitio en producción y habilitar flujos de revisión.

​

Convenciones para nombrar branches

Usa nombres claros y descriptivos que indiquen el propósito de un branch.

Usa:

• fix-broken-links
• add-webhooks-guide
• reorganize-getting-started
• ticket-123-oauth-guide

Evita:

• temp
• my-branch
• updates
• branch1

​

Crear una rama

Usando el editor web

1. Haz clic en el nombre de la rama en la barra de herramientas del editor.
2. Haz clic en Create new branch.
3. Escribe un nombre descriptivo.
4. Si tienes cambios sin guardar, elige si quieres llevarlos a la nueva rama o dejarlos en tu rama actual.
5. Haz clic en Create branch.

Usando desarrollo local

1. Crea una rama desde tu terminal

   git checkout -b branch-name
   

   Esto crea la rama y cambia a ella en un solo comando.

2. Envía la rama a GitHub

   git push -u origin branch-name
   

   La opción -u configura el seguimiento para que en futuros envíos solo necesites ejecutar git push.

​

Guardar cambios en una branch

Usar el editor web

Selecciona el botón Save as commit en la parte superior derecha de la barra de herramientas del editor. Esto crea una confirmación y sube tu trabajo a tu branch automáticamente.

Usar desarrollo local

Prepara, confirma y sube tus cambios.

git add .
git commit -m "Describe your changes"
git push

​

Cambiar de branch

Usar el editor web

1. Haz clic en el nombre del branch en la barra de herramientas del editor para abrir el menú desplegable de branches.
2. Busca un branch por nombre o desplázate por la lista.
3. Haz clic en el branch al que quieres cambiar.

Cada branch en el menú desplegable muestra un indicador de estado para que puedas ver si está listo, sincronizándose o ha fallado.

Los cambios sin guardar se pierden al cambiar de branch. Guarda tu trabajo primero.

Usar el entorno de desarrollo local

Cambia a un branch existente:

git checkout branch-name

O crea y cambia en un solo comando:

git checkout -b new-branch-name

​

Fusionar branches

Cuando tus cambios estén listos para su publicación, crea una solicitud de extracción para fusionar tu branch en la rama de implementación.