Aspectos básicos sobre Git y GitHub para Docs

Información general

Como colaborador del contenido de Docs interactuará con múltiples herramientas y procesos. Además, trabajará en paralelo con otros colaboradores en el mismo proyecto, posiblemente sobre el mismo contenido e incluso al mismo tiempo. Todo esto es posible gracias al software de Git y GitHub.

Git es un sistema de control de versiones de código abierto. Facilita este tipo de colaboración de proyectos a través del control de versiones distribuido de los archivos que residen en los repositorios. Básicamente, Git permite integrar los flujos de trabajo realizados por varios colaboradores a lo largo del tiempo en relación con un repositorio determinado.

GitHub es un servicio de hospedaje basado en Web de repositorios de Git, como los que se usan para almacenar contenido de docs.microsoft.com. Para un proyecto concreto, GitHub hospeda el repositorio principal, del que los colaboradores pueden realizar copias para llevar a cabo su propio trabajo.

Git

Si está familiarizado con los sistemas centralizados de control de versiones (como Team Foundation Server, SharePoint o Visual SourceSafe), observará que Git tiene un flujo de trabajo de colaboración y una terminología exclusivos para admitir su modelo distribuido. Por ejemplo, no hay ningún bloqueo de archivo que suela estar asociado con las operaciones de protección y desprotección. De hecho, Git realmente se ocupa de los cambios a un nivel más pormenorizado, ya que compara los archivos byte por byte.

Git también una estructura en capas para almacenar y administrar el contenido de un proyecto:

• Repositorio: se conoce también como repo y se trata de la unidad de almacenamiento más grande. Un repositorio contiene una o varias ramas.
• Rama: unidad de almacenamiento que contiene los archivos y las carpetas que componen el conjunto de contenido de un proyecto. Las ramas separan los flujos de trabajo, a los que se suele hacer referencia como versiones. Las colaboraciones siempre se realizan en una rama específica, a la que están limitadas exclusivamente. Todos los repositorios contienen una rama predeterminada (que suele denominarse "principal") y una o varias ramas destinadas a fusionarse en la rama predeterminada. La rama predeterminada sirve como la versión actual y la "única fuente de confianza" del proyecto. Se trata del elemento principal a partir del que se crean todas las demás ramas del repositorio.

Los colaboradores interactúan con Git para actualizar y manipular los repositorios tanto a nivel local como en GitHub:

• La colaboración se puede realizar de forma local con herramientas como la consola de Git Bash, que admite los comandos de Git para administrar los repositorios locales y establecer la comunicación con los repositorios de GitHub.
• A través de www.github.com, donde se integra Git para administrar la conciliación de las colaboraciones que se dirigen de nuevo al repositorio principal.

GitHub

Todos los flujos de trabajo empiezan y terminan en GitHub, donde se almacena el repositorio principal de cualquier proyecto de Docs específico. Las copias que los colaboradores crean para su propio uso se distribuyen entre varios equipos. Estas copias se concilian finalmente en el repositorio de GitHub principal del proyecto.

Organización de directorios

Como se ha mencionado anteriormente, la rama predeterminada de un proyecto sirve como la versión actual del contenido del proyecto. El contenido de la rama predeterminada y de las ramas creadas a partir de ella se alinea de forma general con la organización de los artículos en las páginas de Docs correspondientes. Los subdirectorios se usan para separar el contenido similar (como los servicios) y el contenido multimedia (como los archivos de imagen), e "incluyen" archivos, que permiten reutilizar el contenido.

Por norma general, encontrará un directorio principal articles que parte directamente de la raíz del repositorio. El directorio de artículos contiene un conjunto de subdirectorios. Los artículos de los subdirectorios presentan el formato de archivos Markdown, que usan una extensión .md. En algunos repositorios compatibles con varios servicios se usa un subdirectorio /articles genérico, como el repositorio Azure-Docs. En otros es posible que se use un nombre específico del servicio, como el repositorio IntuneDocs, en el que se usa /IntuneDocs.

En la raíz de este directorio, puede encontrar artículos generales relacionados con el servicio o producto general. Además, normalmente puede encontrar otra serie de subdirectorios, que concilian las características y los servicios o escenarios comunes. Por ejemplo, los artículos sobre "máquinas virtuales" de Azure se encuentran en el subdirectorio /virtual-machines, y los artículos de "comprensión y exploración" de Intune, en el subdirectorio /understand-explore.

Subdirectorio multimedia

Cada directorio de artículos contiene un subdirectorio /media para los archivos multimedia correspondientes. Los archivos multimedia contienen las imágenes que usan los artículos que tienen referencias de imagen.

Subdirectorio de archivos de inclusión

Siempre que tengamos contenido reutilizable que se comparta entre dos o más artículos, se coloca en un subdirectorio /includes que parte directamente del directorio articles principal. En un archivo Markdown que use el archivo de inclusión, se coloca una extensión de Markdown "include" correspondiente en la ubicación en la que debe estar la referencia al archivo de inclusión.

Consulte la referencia de Markdown sobre la sintaxis Includes para obtener más información.

Plantilla de archivo Markdown

Para mayor comodidad, el directorio raíz de cada repositorio suele contener un archivo de plantilla Markdown denominado template.md. Puede usar este archivo de plantilla como un "archivo de inicio" si necesita crear un artículo que quiere enviar al repositorio. El archivo contiene los siguientes elementos:

• Un encabezado de metadatos en la parte superior, delimitado por dos líneas de tres guiones. Incluye las diferentes etiquetas que se usan para realizar el seguimiento de la información relacionada con el artículo. Los metadatos de los artículos habilitan ciertas funcionalidades, como la atribución de autor, la atribución de colaborador, las rutas de navegación y las descripciones de los artículos. También incluyen optimizaciones del motor de búsqueda, así como procesos de creación de informes que Microsoft usa para evaluar el rendimiento del contenido. Por lo tanto, los metadatos son importantes.
• Una sección de metadatos en la que se describen las diferentes etiquetas y valores de metadatos. Si no está seguro de los valores que debe usar en la sección de metadatos, puede dejarlos en blanco o comentarlos con un hashtag inicial (#), y el revisor de la solicitud de incorporación de cambios del repositorio los revisará o los completará.
• Varios ejemplos del uso de Markdown para dar formato a los elementos de un artículo.
• Instrucciones generales sobre el uso de extensiones de Markdown, que puede usar para varios tipos de alertas.
• Ejemplos de vídeo insertado mediante un iframe.
• Instrucciones generales sobre el uso de extensiones de docs.microsoft.com, que puede usar para controles especiales, como botones y selectores.

Solicitudes de incorporación de cambios

Una solicitud de incorporación de cambios es un método cómodo para que un colaborador proponga una serie de cambios aplicables a la rama predeterminada. Los cambios (conocidos también como confirmaciones) se almacenan en la rama de un colaborador, de tal forma que se permite a GitHub modelar primero el impacto que tiene fusionarlos en la rama predeterminada. Una solicitud de incorporación de cambios también sirve como un mecanismo para proporcionar comentarios al colaborador sobre un proceso de compilación o validación, para que el revisor de la solicitud pueda resolver los posibles problemas o preguntas antes de que los cambios se fusionen en la rama predeterminada.

Hay dos maneras de contribuir por solicitud de extracción, en función del tamaño de los cambios que quiere proponer. Trataremos esta cuestión más a fondo posteriormente, en la sección sobre el flujo de trabajo de GitHub de esta guía.