Aspectos básicos sobre Git y GitHub para documentación de Microsoft Learn

  • Artículo

Información general

Como colaborador de la documentación de Microsoft Learn, interactuará con varias 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 Microsoft Learn. Para un proyecto concreto, GitHub hospeda el repositorio principal, del que los colaboradores pueden realizar copias para llevar a cabo su propio trabajo.

En este artículo se definen los términos clave que forman parte del flujo de trabajo de Microsoft Learn. También proporciona información general sobre los repositorios de Git y GitHub, y explica cómo se organiza el contenido para la documentación técnica de Microsoft.

Sucursal

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.

El aislamiento de cambios relacionados en una rama específica permite controlar e incorporar dichos cambios de forma independiente. En realidad, en función del tipo de trabajo que realice, podría terminar fácilmente con varias ramas de trabajo en el repositorio. No es raro trabajar en varias ramas al mismo tiempo, pues cada una de ellas representa un proyecto diferente.

Todos los repositorios contienen una rama predeterminada (normalmente denominada "main") y una o varias ramas de trabajo en curso (a las que llamamos ramas de trabajo) que aún no se han integrado 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.

Siempre que incorpore un conjunto de cambios relacionados de forma lógica, un procedimiento recomendado consiste en crear una rama de trabajo para administrar los cambios. No se recomienda realizar cambios en la rama predeterminada directamente.

Bifurcar

Este término se utiliza normalmente como sustantivo para referirse a una copia de un repositorio principal de GitHub. En la práctica, una bifurcación no es más que otro repositorio. No obstante, resulta especial por el hecho de que GitHub establece una nueva conexión con el repositorio principal o primario. Este término se utiliza a veces como verbo, como en "Primero debe bifurcar el repositorio".

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. En cambio, 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. Para más información sobre las ramas, consulte la sección Rama de este artículo.

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

Nota:

Aunque las instrucciones de la documentación se basan en el uso de GitHub, algunos equipos usan Visual Studio Team Services para hospedar los repositorios de Git. El cliente Visual Studio Team Explorer proporciona una interfaz gráfica de usuario (GUI) para interactuar con los repositorios de Team Services, que es una alternativa al uso de los comandos de Git a través de una línea de comandos.
Además, muchas de las instrucciones siguientes se han desarrollado como procedimientos recomendados aprendidos a lo largo de años de experiencia en el hospedaje del contenido del servicio de Azure en GitHub. Pueden ser necesarias en algunos repositorios de Microsoft Learn.

Todos los flujos de trabajo empiezan y terminan en GitHub, donde se almacena el repositorio principal de cualquier proyecto de documentación 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

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 Microsoft Learn correspondientes. Los subdirectorios se utilizan para separar artículos similares (como servicios), contenidos multimedia (como archivos de imagen) y archivos "include" (que permiten reutilizar contenidos).

Subdirectorio artículos

Por norma general, encontrará un directorio principal articles que parte directamente de la raíz del repositorio. El directorio articles contiene un conjunto de subdirectorios. Los artículos de los subdirectorios tienen el formato de archivos Markdown con 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 lo siguiente:

  • 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 documentación técnica de Microsoft, que puede usar para controles especiales, como botones y selectores.

Origen

Este término es el nombre asignado a la conexión entre el repositorio local y el repositorio a partir del que se ha realizado la clonación. En el flujo de trabajo de Microsoft Learn, el origen representa la conexión a la bifurcación. Este término se utiliza a veces como un moniker para el propio repositorio de origen, como en "Recuerde empujar sus cambios al origen".

Solicitudes de incorporación de cambios

Una solicitud de incorporación de cambios (PR) es una solicitud para que el propietario de un contenido incorpore sus cambios en el documento original oficial. Una solicitud de incorporación de cambios permite el modelo de colaboración de GitHub. Para ello, se solicita que se "incorporen" los cambios de la rama de trabajo y se combinen con los de otra rama. En la mayoría de los casos, la otra rama es la rama predeterminada en el repositorio principal.

Una solicitud de incorporación de cambios también sirve como un mecanismo para proporcionar comentarios al colaborador sobre el proceso de Microsoft Learn, para que el revisor de la solicitud pueda resolver los problemas o preguntas antes de que los cambios se fusionen en la rama predeterminada.

Control remoto

Una conexión con nombre a un repositorio remoto, como la conexión remota con el "origen" o con el repositorio "ascendente". Git hace referencia a esto con el término "conexión remota", ya que se usa para hacer referencia a un repositorio hospedado en otro equipo. En el flujo de trabajo de Microsoft Learn, un remoto es siempre un repositorio de GitHub.

Ascendente

Como la conexión remota al origen, el término "ascendente" se corresponde con una conexión con nombre a otro repositorio. En el flujo de trabajo de Microsoft Learn, el flujo ascendente representa la conexión entre su repositorio local y el repositorio principal desde el que se creó su bifurcación. Este término se utiliza a veces como un apodo para el propio repositorio aguas arriba, como en "Recuerde tirar de los últimos cambios de la corriente ascendente".

Saber más

Si no está familiarizado con Git o GitHub, estos recursos pueden ayudarle a aprender, ser productivo o responder a preguntas.

Recursos de control de código fuente de Git

Recursos de GitHub

Preguntas más frecuentes

¿Qué es Git?

Git ayuda a realizar un seguimiento de los cambios cuando muchas personas trabajan juntas en el código del equipo. Es como una máquina de tiempo para el código, por lo que puedes ver lo que ha cambiado y volver atrás si es necesario.

¿Por qué usar Git?

Porque funciona genial para el trabajo en equipo. Git hace posible que muchas personas trabajen en el mismo proyecto sin afectar al trabajo del resto. También ayuda a corregir errores con facilidad.

¿Cómo funciona Git?

Git almacena todas las versiones del código de un proyecto. Cuando se realizan cambios, Git toma una imagen (como una instantánea) de las diferencias. Puedes crear versiones diferentes al mismo tiempo sin ningún problema.

¿Qué son las ramas en Git?

Las ramas son como rutas de acceso diferentes en un proyecto. Permiten que las personas trabajen en cosas nuevas sin modificar el proyecto principal. Más adelante, pueden devolver estos cambios al proyecto principal.

¿Qué es una confirmación en Git?

Una confirmación es como un punto de guardado. Es una manera de registrar los cambios realizados. Cada confirmación tiene un identificador único y una nota que indica lo que se cambió.

¿Qué es GitHub?

GitHub es un sitio web donde puedes almacenar los proyectos de Git. Es como un gran centro para compartir y trabajar en el código junto a otros usuarios. También ayuda a realizar un seguimiento de quién cambió qué.

¿En qué se diferencian GitHub y Git?

Git es la herramienta para realizar el seguimiento de los cambios, mientras que GitHub es el lugar para almacenar los proyectos y trabajar en equipo. GitHub usa Git para hacer su magia.

¿GitHub es gratuito?

Sí, para los proyectos que todo el mundo puede ver. Sin embargo, para proyectos privados (solo para ti y tu equipo), es posible que tengas que pagar. Hay diferentes planes con características adicionales.

¿Qué son las solicitudes de incorporación de cambios en GitHub?

Las solicitudes de incorporación de cambios son como pedir que coloques los cambios en el proyecto principal. Las personas puede revisar y analizar los cambios antes de que se añadan.

¿Cómo de seguro es GitHub?

GitHub se toma en serio la seguridad. Se usan códigos y reglas especiales para asegurarse de que solo las personas adecuadas pueden acceder y cambiar el código. También puedes agregar niveles de seguridad adicionales, como la autenticación en dos fases, para mayor seguridad.