Aspectos básicos de la documentación de Git y GitHub
Información general
Si solo necesita hacer cambios menores de texto en los artículos, no necesita comprender los detalles de este artículo. Este artículo describe el flujo de trabajo para realizar ediciones importantes, como la creación de nuevos artículos y la adición de imágenes, o para la realización de ediciones continuas en la documentación de Adobe.
Como colaborador del contenido de documentación de Adobe, puede interactuar con varias herramientas y procesos. Puede trabajar en paralelo con otros colaboradores del mismo proyecto, posiblemente en el mismo contenido e incluso al mismo tiempo. Todo esto es posible a través del software Git y GitHub.
Git es un sistema de código abierto de control de versiones que permite la colaboración. Varios colaboradores pueden trabajar en archivos que residen en repositorios.
GitHub es un servicio de alojamiento basado en la web para repositorios Git, como los que se usan para almacenar contenido de docs.adobe.com. En un proyecto, GitHub aloja el repositorio principal desde el cual los colaboradores pueden crear copias para realizar su propio trabajo.
Git
Git ofrece un flujo de trabajo de contribución único y una terminología propia que hacen posible su modelo distribuido. Por ejemplo, no existen los bloqueos de archivo que normalmente se asocian con las operaciones de check-out/check-in. Git permite resolver los cambios de manera aún más precisa, comparando archivos byte a byte.
Git también utiliza una estructura jerárquica para almacenar y administrar el contenido de un proyecto:
- Repositorio: también denominado repo, es la unidad de almacenamiento más alta. Un repositorio puede contener tanto una como varias ramas.
- Rama: todos los repositorios contienen una rama predeterminada (normalmente llamada “principal”) y una o más ramas que están destinadas a fusionarse en la rama principal. La rama principal sirve como la versión actual y el origen desde la que se publican los contenidos. Es el nivel superior desde el que se crean todas las demás ramas del repositorio.
Los colaboradores interactúan con Git para actualizar y manipular repositorios en los niveles local y GitHub:
- Localmente a través de herramientas como GitHub Desktop.
- A través de www.github.com, que integra Git para administrar la reconciliación de las contribuciones que regresan al repositorio principal.
GitHub
Todos los flujos de trabajo comienzan y finalizan en el nivel de GitHub, donde se almacena el repositorio principal de cualquier proyecto de documentación de Adobe. Las copias que los colaboradores crean para su propio uso se distribuyen entre varios ordenadores. Al final, estas copias se reconcilian nuevamente en el repositorio de GitHub principal del proyecto.
Organización del directorio
La rama predeterminada de un proyecto sirve como versión actual del contenido del proyecto. El contenido de la rama principal, y de las ramas creadas a partir de ella, se ajusta a la organización de los temas del artículo. Los subdirectorios se utilizan para organizar contenido y recursos de imagen.
Normalmente, se puede encontrar un directorio help principal en la raíz del repositorio. El directorio de artículos contiene un conjunto de subdirectorios. Los artículos de los subdirectorios tienen el formato de archivos Markdown que utilizan la extensión .md.
Dentro de la raíz de este directorio, puede encontrar artículos generales relacionados con el servicio general o el producto. Es habitual encontrar otra serie de subdirectorios que coinciden con las características, servicios o escenarios comunes.
Directorio de recursos
Los directorios de guías del usuario contienen subdirectorios /assets para archivos de imagen a los que se hace referencia dentro de un directorio.
Solicitudes de extracción
Una solicitud de extracción permite a un colaborador proponer un conjunto de cambios que se aplicarán a la rama predeterminada. Los cambios (también conocidos como commits) se almacenan en la rama de un colaborador, por lo que GitHub puede modelar primero el impacto de la fusión en la rama predeterminada. Una solicitud de extracción también sirve como mecanismo para proporcionar al colaborador comentarios desde un proceso de generación/validación, y al revisor de la solicitud de extracción para resolver posibles problemas o preguntas antes de que los cambios se fusionen en la rama predeterminada.
Existen dos formas de contribuir por solicitud de extracción, según el tamaño de los cambios que desee proponer. Explicaremos esto en detalle más adelante, en la sección Flujo de trabajo de GitHub de esta guía.