Saltar al contenido principal
Git es un sistema de control de versiones que te permite seguir los cambios en tu documentación y colaborar con los miembros del equipo. Con Git, para cada archivo de tu proyecto, puedes ver qué cambió con el tiempo, quién hizo los cambios, cuándo y por qué. Git también facilita volver a versiones anteriores de los archivos si necesitas deshacer cambios. El editor web realiza operaciones de Git en segundo plano. Con una comprensión de Git, puedes trabajar de forma más eficaz con el editor web y colaborar con los miembros del equipo que usan entornos de desarrollo locales.

​
¿Por qué Git para la documentación?

Git proporciona funcionalidades esenciales para gestionar documentación.
  • Historial de versiones: Consulta qué cambió, cuándo y por qué en cada archivo.
  • Colaboración: Varias personas pueden trabajar en distintas partes simultáneamente.
  • Seguridad: Permite experimentar sin romper la documentación en producción.
  • Flujos de revisión: Los miembros del equipo pueden revisar los cambios antes de publicarlos.
  • Recuperación: Deshaz errores o restaura versiones anteriores.

​
¿Nuevo en Git?

Si eres completamente nuevo en Git y en el control de versiones, aquí tienes una ruta para empezar.
1

Usa primero el editor web.

El editor web gestiona las operaciones de Git automáticamente.
  • Visualiza cualquier cambio a medida que lo haces.
  • Crea ramas con un solo clic.
  • Publica y crea solicitudes de extracción sin usar comandos de Git.
Esto te permite aprender conceptos de Git sin usar la línea de comandos.
2

Aprende haciendo.

A medida que usas el editor web, estás usando Git.
  • Guardar cambios crea una confirmación.
  • Crear rama crea una rama de Git.
  • Publicar abre una solicitud de extracción para revisión.
3

Explora el desarrollo local cuando sea útil.

Puedes gestionar tu documentación completamente con el editor web y el dashboard, pero puedes personalizar tu flujo de trabajo trabajando en tu entorno local.
  • Crea y edita archivos en tu editor favorito.
  • Usa Git desde la línea de comandos, GitHub Desktop o una extensión en tu editor.
  • Obtén una vista previa de los cambios localmente antes de publicar.
  • Integra tu flujo con otras herramientas como tickets de soporte, seguimiento de incidencias y sistemas de diseño.

​
Conceptos fundamentales de Git

Una rama apunta a una confirmación específica en tu repositorio. Tu documentación en producción se compila desde una rama de implementación. Puedes tener cualquier número de otras ramas con cambios que aún no se han publicado en tu documentación en producción. Si quieres incorporar los cambios de una rama en tu documentación en producción, puedes fusionar la rama en tu rama de implementación mediante una solicitud de extracción.Usa ramas para trabajar en cambios sin afectar tu documentación en producción, experimentar de forma segura con nuevas funcionalidades y obtener revisiones antes de publicar.
Descarga una copia completa de un repositorio en tu computadora, incluidos todos los archivos y el historial completo. Cuando clonas un repositorio, obtienes todo lo necesario para trabajar de forma local.
git clone https://github.com/your-org/your-repo
Una instantánea guardada de tus cambios en un momento específico. Cada confirmación incluye un mensaje que describe qué cambió y crea un registro permanente en el historial de tu proyecto.
Ocurre cuando dos personas cambian de forma diferente la misma parte de un archivo. Git te pide que elijas manualmente qué cambio conservar o que combines ambos cambios.
La rama principal de tu proyecto. Los cambios en esta rama se publican automáticamente en tu sitio de documentación. A menudo se llama main, pero puedes configurar cualquier rama como tu rama de implementación.
Un diff (o diferencia) muestra los cambios entre dos versiones de un archivo. Al revisar solicitudes de extracción, los diffs resaltan qué es diferente respecto a la versión original del archivo.
Combina los cambios de una rama en otra. Normalmente se hace mediante una solicitud de extracción, después de la revisión, para incorporar el trabajo de nuevas funcionalidades en tu rama de implementación.
Obtén los cambios más recientes desde el repositorio remoto en tu copia local. Te mantiene al día con el trabajo de otras personas.
git pull
Una forma de proponer la fusión de tus cambios en una rama con tu documentación en producción. Permite la revisión y la discusión antes de que los cambios se publiquen. Comúnmente llamada PR y también llamada merge request en GitLab.
Envía tus confirmaciones locales al repositorio remoto. Esto hace que tus cambios estén disponibles para otras personas y puede desencadenar implementaciones automáticas.
git push
Una versión de tu repositorio alojada en un servidor. Tu repositorio local se conecta a un repositorio remoto para enviar (push) y obtener (pull) cambios.
El código fuente de tu documentación, con todos los archivos y su historial, que conforman las páginas de tu sitio de documentación. El editor web se conecta a tu repositorio de documentación para acceder y modificar contenido.
Prepara cambios específicos para incluirlos en tu próxima confirmación. La preparación (staging) te permite organizar los cambios en confirmaciones lógicas.
git add filename.mdx

​
Cómo usa Git el editor web

El editor web se conecta a tu repositorio de Git a través de la Aplicación de GitHub o la integración con GitLab y automatiza operaciones comunes de Git. Cuando:
  • Abres un archivo: El editor obtiene la versión más reciente de tu repositorio, asegurando que siempre trabajes con contenido actualizado.
  • Realizas cambios: El editor rastrea tus cambios como un borrador que puede convertirse en una confirmación cuando estés listo para guardar tu trabajo.
  • Guardas cambios: El editor crea una confirmación con tus cambios, preservando tu trabajo en el historial del proyecto.
  • Creas una branch: El editor crea una nueva branch en tu repositorio que puede ser utilizada por cualquier persona con acceso al repositorio para colaborar y revisar cambios.
  • Publicas en tu rama de implementación: El editor confirma y hace push directamente a tu rama de implementación, lo que publica tus cambios de inmediato.
  • Publicas en otras branches: El editor crea una solicitud de extracción, lo que te permite obtener comentarios de otros antes de fusionar tus cambios en tu rama de implementación.

​
Flujos de trabajo habituales

​
Publicar directamente en tu rama de implementación

  1. Abre el archivo en el editor web.
  2. Realiza los cambios.
  3. Haz clic en Publish.
  4. Los cambios se reflejan en el repositorio y se implementan automáticamente.

​
Trabajar en una rama de funcionalidad

Para crear solicitudes de extracción desde el editor web, debes tener habilitada una regla de protección de ramas que requiera solicitudes de extracción antes de que los cambios puedan fusionarse en tu rama de implementación. Sin reglas de protección de ramas, los cambios en las ramas se fusionan en tu rama de implementación cuando se publican.
  1. Crea una rama desde el menú desplegable de ramas en la barra de herramientas del editor.
  2. Realiza y guarda cambios en la rama.
  3. Haz clic en Publish para crear una solicitud de extracción.
  4. Fusiona la solicitud de extracción cuando esté lista.

​
Revisar los cambios antes de publicar

1

Crea una branch de funcionalidad.

Trabaja en los cambios en una branch distinta de tu rama de implementación para poder compartir y revisar los cambios antes de publicar.
2

Haz tus cambios.

Edita los archivos y confirma los cambios en la branch de funcionalidad.
3

Crea una solicitud de extracción.

Crea una solicitud de extracción para proponer fusionar los cambios de tu branch de funcionalidad en la rama de implementación.
4

Revisa el diff.

Revisa tus cambios. La solicitud de extracción muestra las diferencias línea por línea con respecto a la versión original del archivo.
5

Obtén comentarios del equipo.

Los miembros del equipo pueden comentar en líneas específicas o sobre los cambios en general. Realiza los ajustes necesarios y confirma los cambios en la branch de funcionalidad.
6

Fusiona cuando se apruebe.

Fusiona la solicitud de extracción para publicar los cambios en tu documentación en vivo.

​
Mejores prácticas de Git

Cada equipo desarrolla sus propios flujos de trabajo y preferencias, pero estas son algunas buenas prácticas generales para empezar.
  • Escribe mensajes de confirmación descriptivos: Sé específico sobre qué cambió usando un lenguaje activo. Fix broken link in API docs es más informativo que update page.
  • Usa nombres de branch descriptivos: Los nombres de las branch deben reflejar el propósito de la branch. Usa nombres informativos como update-api-reference en lugar de nombres genéricos como temp o my-branch.
  • Mantén las branch enfocadas: Mantén los cambios en una branch centrados en una tarea o proyecto específico. Esto facilita las revisiones y reduce los conflictos.
  • Elimina las branch después de hacer merge: Elimina las branch cuando ya no las necesites para mantener tu repositorio ordenado.
  • Haz pull antes de hacer push: Siempre haz pull de los cambios más recientes antes de hacer push para evitar conflictos. El editor web hace esto automáticamente.
  • Revisa primero tus propios cambios: Revisa el diff antes de crear una solicitud de extracción.