Conceptos de Git para la documentación
Aprende los fundamentos de Git para flujos docs-as-code: repositorios, branches, commits y colaboración mediante pull requests en tu documentación.
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.
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.
Si eres completamente nuevo en Git y en el control de versiones, aquí tienes una ruta para empezar.
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.
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.
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.
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 y los convierte en una confirmación cuando guardas 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.
- Abre el archivo en el editor web.
- Realiza los cambios.
- Haz clic en Publish.
- Los cambios se reflejan en el repositorio y se implementan automáticamente.
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.
- Crea una rama desde el menú desplegable de ramas en la barra de herramientas del editor.
- Realiza y guarda cambios en la rama.
- Haz clic en Publish para crear una solicitud de extracción.
- Fusiona la solicitud de extracción cuando esté lista.
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.
Haz tus cambios.
Edita los archivos y confirma los cambios en la branch de funcionalidad.
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.
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.
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.
Fusiona cuando se apruebe.
Fusiona la solicitud de extracción para publicar los cambios en tu documentación en vivo.
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 docses más informativo queupdate 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-referenceen lugar de nombres genéricos comotempomy-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.