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 GitHub.com y GitHub Enterprise Server que envían al lector directamente a la documentación del producto que está usando.

Procedimiento y lugar del control de versiones

El control de versiones del contenido de GitHub Docs es de origen único para evitar la repetición y mantener la prosa con un enfoque 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 control de versiones de un fragmento de contenido completo.
```
versions:
  PRODUCT: 'VERSIONS'
  PRODUCT: 'VERSIONS'
  ...
```
En el ejemplo siguiente se muestra el contenido con versiones de GitHub.com 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 sobre versiones para los usuarios de planes de GitHub.com, 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 en desuso (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.js 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 elementos secundarios.

Por ejemplo, el siguiente texto preliminar de YAML efectuará un control de versiones en un artículo de GitHub Enterprise Server 2.20 y versiones posteriores y de los planes Gratis, 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 crear una versión de una página para un intervalo de versiones. En el ejemplo siguiente se versiona la página con las versiones de GitHub.com y GitHub Enterprise Server 3.1 y 3.2 únicamente:

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

Control de versiones con operadores condicionales 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 realizar el control de versiones del contenido adecuadamente mediante el texto preliminar versions y usar condicionales Liquid para describir las opciones adicionales de GitHub.com.

Notas:

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 uses `not` en intervalos)

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.

Basta con que agregue un guion (-) a la izquierda, a la derecha o a ambos lados para indicar que no debe haber ninguna nueva línea en ese lado.

{%- ifversion fpt %}

Por ejemplo, para versionar un paso de un procedimiento, en lugar de agregar control de versiones de Liquid para el paso a partir del 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 control de de versiones Liquid en su propia línea y usar el control de espacio en blanco para quitar la nueva 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 de característica único (o "marca") para agrupar y generar prosa de la versión a lo largo del contenido. Cuando una característica llega a productos adicionales, solo tienes que realizar un cambio en el control de versiones de YAML en el archivo dentro de data/features/.

Administración de características

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

Nota: No elimine 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 preliminar de versiones. Para más información, consulta "Versiones" en el archivo LÉAME del repositorio github/docs.

Condicionales de Liquid

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

Texto preliminar

También puede usar la característica en textos preliminares en 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. Estas son algunas sugerencias para mejorar la experiencia de escritura, lectura y revisión de la sintaxis de control de versiones. Ninguno de estos procedimientos es obligatorio y encontrarás casos excepcionales, pero están diseñados como heurística útil para ayudarte a pensar en 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 capturas de pantalla del control de versiones si es posible, 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 control de versiones de las capturas de pantalla afectaría a la comprensión en un grado significativo.
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 representada de los cambios que estás realizando y cambia a cada versión disponible de la página como parte de la autorrevisiones.

Evitar la repetición tanto como sea posible

Use la sintaxis de control de versiones dentro de una frase o párrafo para diferenciar la prosa de dos planes o productos diferentes. Un colaborador puede editar solo un párrafo con instrucciones de control de versiones, en lugar de tener en cuenta bloques más grandes de texto con versiones y modificar prosas similares pero con versiones diferentes 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 analizar para un colaborador, considera la posibilidad de repetir la sugerencia para que la prosa sea más fácil de mantener.

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

Puedes hacer {% ifversion fpt %}"algo"{% elsif ghec %}"algo más"{% 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, realiza un control de versiones explícito para esos productos. Una sintaxis como not, y else en particular, puede ser imprecisa. El resultado final de not y else depende del texto preliminar de cada artículo, por lo que un colaborador deberá realizar más investigación para comprender la prosa con este 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 texto preliminar al empezar a editar, ya que esto puede ayudarte a comprender cómo se comportarán not y else en las instrucciones Liquid, o cambia cuando habilites las nuevas versiones en el texto preliminar.

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