Documentación sobre el control de versiones

En GitHub Docs, se proporcionan versiones de nuestra documentación que reflejan las diferencias de interfaz de usuario y funcionalidad entre las diversas ofertas de productos principales de GitHub. Los colaboradores pueden usar la sintaxis de control de versiones para limitar el contenido a una oferta de producto específica.

La sintaxis de control de versiones permite al lector elegir manualmente la versión de la documentación que se aplica al producto que va a usar. Las direcciones URL de GitHub Docs también pueden incluir información de control de versiones, la cual permite vínculos de una versión de GitHub Docs a otra para enviar al lector directamente a la documentación del producto que está usando.

Cómo y dónde versionar

El versionado del contenido de GitHub Docs es de fuente única para evitar la repetición y mantener la prosa según el principio DRY. En el caso de los artículos, puedes aplicar el control de versiones a un archivo Markdown individual con metadatos de YAML y, posteriormente, usar instrucciones condicionales dentro de la prosa del archivo para indicar al sitio qué texto mostrar en función de la versión que seleccione el lector. El enfoque de origen único contrasta con la creación de archivos independientes que reflejan cada versión del contenido.

Hay dos tipos de sintaxis de control de versiones para GitHub Docs.

YAML: se usa con más frecuencia en el texto preliminar de YAML dentro de los archivos Markdown en content/, pero también en muchos tipos de archivos YAML en data/. Indica el versionado de un contenido completo.
```
versions:
  PRODUCT: 'VERSIONS'
  PRODUCT: 'VERSIONS'
  ...
```
En el ejemplo siguiente se muestra el contenido con versiones de Free, Pro y Team y todas las versiones de GitHub Enterprise Server.
```
versions:
  fpt: *
  ghes: *
```
Liquid: se usa dentro de los archivos Markdown en content/ y data/reusables/, cadenas variables dentro de archivos YAML en data/variables/ o cadenas dentro de data/glossaries/external.yml. Indica qué texto debe aparecer cuando un lector elige una versión para un contenido que tiene varias versiones definidas en el texto preliminar de YAML.
- Control de versiones basado en productos:
```
{% ifversion SHORT-PRODUCT-NAME %} ... {% endif %}
```
- Control de versiones basado en características:
```
{% ifversion FEATURE-NAME %} ... {% endif %}
```

Acerca de las distintas versiones de GitHub

Proporcionamos documentación versionada para los usuarios de planes de GitHub, incluidos GitHub Enterprise Cloud y GitHub Enterprise Server. Si existen varias versiones de una página en el sitio, los lectores pueden elegir la versión en el selector de versiones de la parte superior de la página.

GitHub.com

La documentación de GitHub.com tiene dos posibles versiones:

Planes Gratis, Profesional o de Equipo

Los planes Gratis, Profesional o de Equipo de GitHub.com, usan free-pro-team@latest. El nombre corto es fpt.

GitHub Enterprise Cloud

Para GitHub Enterprise Cloud, usa enterprise-cloud@latest. El nombre corto es ghec.

GitHub Enterprise Server

La documentación de GitHub Enterprise Server tiene varias versiones y se puede dividir en dos tipos: documentación de las versiones compatibles (se admiten cuatro en cualquier momento), y documentación de las versiones cerrar (no incluimos enlaces a estos documentos en el sitio de documentación, pero mantenemos una instantánea "congelada" de estos documentos a perpetuidad, por lo que se puede seguir accediendo a ellos si se conocen las direcciones URL). Consulta lib/enterprise-server-releases.ts para obtener una lista.

Las versiones se denominan enterprise-server@<release>. El nombre corto es ghes. En los operadores condicionales Liquid, podemos especificar rangos, como ghes > 3.0. Para más información, consulta Control de versiones con operadores condicionales Liquid.

Control de versiones en el texto preliminar de YAML

Puedes usar la propiedad versions dentro del texto preliminar del archivo para definir para qué productos aparecerá un artículo. Los archivos de índice requieren una propiedad versions, pero se versionarán automáticamente en función de las versiones de sus hijos.

Por ejemplo, el siguiente texto preliminar de YAML versionará un artículo para GitHub Enterprise Server 2.20 y versiones posteriores, así como para los planes Gratuito, Profesional o Equipo.

title: About your personal dashboard
versions:
  fpt: '*'
  ghes: '>=2.20'

En el ejemplo siguiente se creará una versión de un artículo para todas las versiones admitidas de GitHub Enterprise Server:

title: Downloading your license
versions:
  ghes: '*'

También puede gestionar las versiones de una página para un rango de lanzamientos. En el ejemplo siguiente se versiona la página solo con Free, Pro y Team, GitHub Enterprise Cloud y GitHub Enterprise Server versiones 3.1 y 3.2:

versions:
  fpt: '*'
  ghec: '*'
  ghes: '>=3.1 <3.3'

Control de versiones con operadores condicionales del lenguaje Liquid

Usamos el lenguaje de plantilla Liquid (específicamente, este puerto Node.js) y una etiqueta personalizada {% ifversion ... %} para crear versiones de nuestra documentación.

Si defines varios productos en la clave versions dentro del texto preliminar de YAML de una página, puedes usar los operadores condicionales ifversion/else (oifversion/elsif/else) en Markdown para controlar cómo representa el sitio el contenido en la página de un producto determinado. Por ejemplo, una característica puede tener más opciones en GitHub.com que en GitHub Enterprise Server, por lo que puedes versionar el contenido adecuadamente mediante el frontmatter versions y usar sentencias condicionales de Liquid para describir las opciones adicionales de GitHub.com.

Nota:

Usa ifversion para el control de versiones basado en productos y el control de versiones basado en características.
No utilice if ni unless.
Asegúrate de que usas elsif y no else if. Liquid no reconoce else if y no representará contenido dentro de un bloque else if.

Operadores de comparación

Para las versiones que no incluyen versiones numeradas (como fpt y ghec), tienes dos opciones:

{% ifversion ghec %}
{% ifversion not ghec %}

En el caso de las versiones que incluyen versiones numeradas (actualmente solo ghes), puedes hacer lo mismo para el contenido que está disponible en todas las versiones o que no está disponible en ninguna de ellas:

{% ifversion ghes %}
{% ifversion not ghes %}

Si necesitas indicar contenido que solo está disponible (o no disponible) en determinadas versiones, puedes usar los operadores siguientes:

Operador	Significado	Ejemplo
`=`	Igual a	`{% ifversion ghes = 3.0 %}`
`>`	Más reciente que	`{% ifversion ghes > 3.0 %}`
`<`	Anterior a	`{% ifversion ghes < 3.0 %}`
`!=`	No igual a

          `{% ifversion ghes != 3.0 %}` (no usar `not` en rangos)

Los operadores Liquid ==, >= y <= no se admiten en GitHub Docs.

Operadores lógicos

Si todos los operandos deben ser true para que la condición sea true, usa el operador and:

{% ifversion ghes > 2.21 and ghes < 3.1 %}

Si al menos un operando debe ser true para que la condición sea true, usa el operador or:

{% ifversion fpt or ghes > 2.21 %}

No uses los operadores && ni ||. Liquid no los reconoce y el contenido no se representará en las versiones previstas.

Control de espacios en blanco

Al usar condicionales de Liquid en listas, puede usar caracteres de control de espacio en blanco para evitar la adición de nuevas líneas y otros espacios en blanco que puedan interrumpir la representación de la lista.

Puede agregar un guion (-) a la izquierda, a la derecha o en ambos lados para indicar que no debe haber ninguna nueva línea u otro espacio en blanco en dicho lado.

{%- ifversion fpt %}

Por ejemplo, para versionar un paso de un procedimiento, en lugar de agregar un control de versionado fluido para el paso comenzando desde el final del paso anterior, de la siguiente manera:

1. This step is for all versions{% ifversion ghes %}
1. This step is for GHES only{% endif %}
1. This step is for all versions

Puede incluir el versionado de Liquid en su propia línea y usar el control de espacio en blanco para eliminar el salto de línea a la izquierda de la etiqueta Liquid. Esto facilita la lectura de la fuente, sin interrumpir la representación de la lista:

1. This step is for all versions
{%- ifversion ghes %}
1. This step is for GHES only
{%- endif %}
1. This row is for all versions

Acerca del control de versiones basado en características

Cuando documentes cualquier cambio o característica nuevo, usa el control de versiones basado en características.

Solo una pequeña minoría de características y cambios se aplicará a un solo producto. La mayoría de las características llegan a GitHub.com y finalmente llegan a todos los productos. En general, cambia "flow" de GitHub.com (incluido GitHub Enterprise Cloud) a GitHub Enterprise Server.

El control de versiones basado en características proporciona "marcas de características" con nombre que simplifican el mantenimiento y el control de versiones de la documentación. Puedes usar un nombre único de característica (o "flag") para agrupar y versionar la prosa a lo largo del contenido. Cuando una función llega a productos adicionales, solo tienes que realizar un cambio en la versión YAML en el archivo dentro de data/features/.

Administración de funcionalidades

Cada característica se administra a través de archivos YAML individuales en data/features/.

Nota:

No elimines data/features/placeholder.yml porque se usa en las pruebas.

Para crear una nueva característica, primero crea un nuevo archivo YAML con el nombre de la característica que deseas usar en este directorio. Para una característica denominada meow, que sería data/features/meow.yml.

Agrega un bloque versions al archivo YAML con los nombres cortos de las versiones en las que está disponible la característica. Por ejemplo:

versions:
  fpt: '*'
  ghec: '*'
  ghes: '>3.1'

El formato y los valores permitidos son los mismos que en la propiedad de versiones de frontmatter. Para obtener más información, consulte Versiones en el archivo LÉAME del repositorio github/docs.

Condicionales de Liquid

Ahora puede usar {% ifversion meow %} ... {% endif %} en archivos de contenido.

Páginas iniciales

También puede usar la función en los metadatos iniciales de los archivos de contenido:

versions:
  feature: 'meow'

Solo puedes usar una entrada feature en versions y el valor de feature solo puede contener un nombre de característica.

Puedes combinar el control de versiones basado en características y el control de versiones estándar en texto preliminar. Al hacerlo, el artículo se incluirá en el superconjunto de todas las versiones especificadas en el archivo de control de versiones basado en características y directamente en el archivo Markdown. Por ejemplo, puedes tener una característica que actualmente solo está disponible en GHEC y se especifica en el control de versiones basado en características. Sin embargo, quieres que el artículo «Acerca de» de esta característica también sea visible en los documentos FPT. En este caso, podrías añadir fpt y feature al bloque versions en el encabezado:

versions:
  fpt: '*'
  feature: 'some-new-feature'

procedimientos recomendados

El contenido con versiones afecta al lector, pero también afecta a cualquier persona que contribuya o revise el contenido. Aquí tienes algunos consejos para mejorar la experiencia de escritura, lectura y revisión de la sintaxis de versionado. Ninguno de estos procedimientos es obligatorio y encontrarás casos límite y extremos, pero están diseñados como una heurística útil que puede asistirte en la reflexión sobre el control de versiones.

Evitar el control de versiones innecesario

Para el lector, obtener una comprensión general es más importante que leer detalles que reflejen con precisión las diferencias entre determinados productos o planes. En un contenido conceptual o de procedimientos, intenta describir características o partes de la interfaz de usuario de una manera general que no requiera sintaxis de control de versiones. Además de ser más fácil de mantener, esto mejora la comprensión de los lectores que consultan la documentación de varios productos.

Hazte esta pregunta: ¿puedo escribir este contenido de una manera que se aplique a todos los productos sin necesidad de control de versiones?"
Intenta evitar el versionado de capturas de pantalla si puedes, dado el esfuerzo necesario para crearlas. Es posible que las diferencias menores entre la copia de la interfaz de usuario no afecten a la comprensión. Si existe texto o elementos de interfaz de usuario específicos del producto, y la captura de pantalla proporciona contexto útil, pregúntate si el versionado de las capturas de pantalla afectaría la comprensión de manera significativa.
No versiones la prosa si puedes explicar un concepto o guiar al lector a través de un procedimiento sin control de versiones para productos específicos.

Al modificar un archivo de contenido existente, revisa el control de versiones existente al principio y a menudo.

Estar al tanto del control de versiones existente te ayudará a asegurarte de que escribes las instrucciones de control de versiones pertinentes, y puede ayudarte a recordar que debes controlar las versiones del nuevo contenido con precisión.

Revisa el control de versiones de toda la página en el texto preliminar tan pronto como empieces a editar.
Revisa el control de versiones en torno al contenido que estás editando.
Revisa la versión visualizada de los cambios que estás realizando y cambia a cada versión de la página disponible como parte de la autorrevisión.

Evitar la repetición tanto como sea posible

Use la sintaxis de versiones dentro de una frase o párrafo para diferenciar la prosa correspondiente a dos planes o productos. Un colaborador puede editar solo un párrafo con declaraciones de versionado, en lugar de tener que considerar bloques más grandes de texto versionado y modificar texto similar pero con diferentes versiones en dos lugares. Un revisor puede sugerir un cambio una vez, en lugar de dejar la misma sugerencia en varios lugares. Pero si el comportamiento difiere drásticamente o el control de versiones dentro de la frase o el párrafo se complica o resulta difícil de interpretar para un colaborador, considera repetirte para que la prosa sea más fácil de mantener.

Usa la sintaxis de versiones dentro de los párrafos para evitar repetir oraciones o párrafos completos.

Puedes hacer {% ifversion fpt %}"algo"{% elsif ghec %}"otra cosa"{% endif %}.
Usa tu propio criterio: en el caso de una prosa que sería complicado escribir o leer sin una gran sintaxis de control de versiones dentro de una frase o párrafo, considera la posibilidad de repetir todo el párrafo en un bloque de versión para cada producto pertinente.

{% ifversion fpt %}

Si usas un plan Gratis, Profesional o Equipo, puedes hacer algunas cosas. Aquí tienes más información sobre las cosas que puedes hacer con un plan Gratis, Profesional o Equipo...

{% elsif ghec %}

Si usas la nube de GitHub Enterprise, puedes hacer más cosas. Aquí tienes más información sobre las cosas que puedes hacer con la nube de GitHub Enterprise...

{% endif %}

Ser explícito, no implícito

Si sabes exactamente qué productos describe el contenido, gestiona las versiones de manera explícita para esos productos. Una sintaxis como not, y else en particular, puede ser imprecisa. El resultado final de not y else viene determinado por el texto preliminar de cada artículo, por lo que un colaborador deberá investigar más a fondo para comprender la prosa con este método de control de versiones. Esto crea la posibilidad de errores. La complejidad del control de versiones implícito aumenta en los elementos reutilizables, en los que los artículos que hacen referencia a los elementos reutilizables pueden tener versiones diferentes y, por tanto, diferentes evaluaciones de not o else. En ocasiones, también presentamos una nueva versión a GitHub Docs cuando GitHub presenta un nuevo producto que cambia el resultado final de not y else cuando agregamos la nueva versión a los artículos existentes.

Recuerda que GitHub ofrece cuatro productos y que GitHub Docs puede mostrar documentación de ocho versiones en total en un momento dado.
Revisa el control de versiones de un artículo completo en el encabezado al empezar a editar, ya que esto puede ayudarte a comprender cómo se comportarán not y else en las declaraciones Liquid, o cambiarán cuando habilites las nuevas versiones en el encabezado.

Comprobar y comunicar el control de versiones a medida que se trabaja en el diseño y la creación de contenido

A veces, un cambio no se incluye en la versión para la que estaba pensado originalmente. Puedes ahorrar tiempo a los revisores y garantizar contenido más preciso mediante la confirmación del control de versiones durante el diseño y la creación de contenido, tanto para versiones como para mejoras.

Considera la posibilidad de crear versiones en el diseño de contenido y comprueba el control de versiones al solicitar revisiones de las partes interesadas para la creación de contenido.
Haz que la revisión sea más fácil para otros escritores y partes interesadas: señala las diferencias entre las versiones de la solicitud de revisión y vincula a versiones representadas específicas del contenido si es necesario.
Confía, pero verifica.

Probar, probar y volver a probar

Tanto si estás escribiendo el contenido como si lo estás revisando, presta atención al plan de diseño de contenido y a los productos afectados, y comprueba el contenido representado en un entorno de ensayo o desarrollo para asegurarte de que el contenido describe con precisión cada producto.

Documentación sobre el control de versiones

En este artículo