Documentation sur le contrôle de version

Sur GitHub Docs, nous fournissons des versions de notre documentation qui reflètent les différences d'interface utilisateur et de fonctionnalités entre les principales offres de produits de GitHub. Les contributeurs peuvent utiliser la syntaxe de contrôle de version pour étendre le contenu à une offre de produit spécifique.

La syntaxe de contrôle de version permet au lecteur de choisir manuellement la version de la documentation qui s'applique au produit qu'il utilise. Les URL GitHub Docs peuvent également inclure des informations sur les versions, ce qui permet aux liens de GitHub.com et GitHub Enterprise Server d'envoyer le lecteur directement à la documentation du produit qu'il utilise.

Comment et où contrôler la version

Le contrôle de version pour le contenu sur GitHub Docs est une source unique pour éviter les répétitions et conserver la prose DRY. Pour les articles, appliquez le contrôle de version à un fichier Markdown individuel avec des métadonnées YAML, puis utilisez des instructions conditionnelles dans la prose du fichier pour indiquer au site quel texte afficher en fonction de la version sélectionnée par le lecteur. L'approvisionnement unique contraste avec la création de fichiers distincts qui reflètent chaque version du contenu.

Il existe deux types de syntaxe de contrôle de version pour GitHub Docs.

• YAML : utilisé le plus souvent dans l'en-tête YAML dans les fichiers Markdown dans content/, mais également dans de nombreux types de fichiers YAML dans data/. Indique le contrôle de version d'un élément de contenu entier.

  versions:
    PRODUCT: 'VERSIONS'
    PRODUCT: 'VERSIONS'
    ...
  

  L'exemple suivant montre le contenu contrôlé pour GitHub.com et toutes les versions de GitHub Enterprise Server.

  versions:
    fpt: *
    ghes: *
  

• Liquide : utilisé dans les fichiers Markdown dans content/ et data/reusables/, chaînes de variables dans les fichiers YAML dans data/variables/ ou chaînes dans data/glossaries/external.yml. Indique quel texte doit apparaître lorsqu'un lecteur choisit une version pour le contenu qui a plusieurs versions définies par l'en-tête YAML.

  • Contrôle de version basé sur le produit :

    {% ifversion SHORT-PRODUCT-NAME %} ... {% endif %}
    

  • Contrôle de version basé sur les fonctionnalités :

    {% ifversion FEATURE-NAME %} ... {% endif %}
    

À propos des différentes versions de GitHub

Nous fournissons une documentation versionnée pour les utilisateurs des plans GitHub.com, y compris GitHub Enterprise Cloud et GitHub Enterprise Server. Si plusieurs versions d'une page existent sur le site, les lecteurs peuvent choisir la version dans le sélecteur de versions en haut de la page.

GitHub.com

La documentation pour GitHub.com comporte deux versions possibles :

Plans Gratuits, Pro ou Team

Pour les plans Gratuits, Pro ou Team sur GitHub.com, utilisez free-pro-team@latest. Le nom abrégé est fpt.

GitHub Enterprise Cloud

Pour GitHub Enterprise Cloud, utilisez enterprise-cloud@latest. Le nom abrégé est ghec.

GitHub Enterprise Server

La documentation de GitHub Enterprise Server a plusieurs versions et peut être divisée en deux types : documentation pour les versions prises en charge (nous prenons en charge quatre versions à la fois) et documentation pour les versions déconseillées (nous ne les lions pas sur le site Documents, mais nous prenons en charge une instantané « figée » de ces documents à perpétuité, afin qu'ils soient toujours accessibles si vous connaissez les URL). Consultez lib/enterprise-server-releases.js pour obtenir une liste.

Les versions sont nommées enterprise-server@<release>. Le nom abrégé est ghes. Dans les opérateurs conditionnels Liquid, nous pouvons spécifier des plages, telles que ghes > 3.0. Pour plus d'informations, consultez « Contrôle de version avec des opérateurs conditionnels Liquid ».

Contrôle de version dans l'en-tête YAML

Vous pouvez utiliser la propriété versions dans la page d'accueil d'un fichier pour définir les produits pour lesquels un article apparaîtra. Les fichiers d'index nécessitent une propriété versions, mais ils seront automatiquement versionnés en fonction des versions de leurs enfants.

Par exemple, l'en-tête YAML suivant versionnera un article pour GitHub Enterprise Server 2.20 et versions ultérieures et Gratuit, Pro ou Team.

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

L'exemple suivant met en version un article pour toutes les versions prises en charge de GitHub Enterprise Server :

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

Vous pouvez également contrôler la version d'une page dans une plage de versions. L'exemple suivant contrôle la version de la page pour GitHub.com et uniquement les versions 3.1 et 3.2 de GitHub Enterprise Server.

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

Contrôle de version avec des opérateurs conditionnels Liquid

Nous utilisons le langage de modèle Liquid (en particulier, ce port Node.js) et une balise personnalisée {% ifversion ... %} pour créer des versions de notre documentation.

Si vous définissez plusieurs produits dans la clé versions d'un en-tête YAML d'une page, vous pouvez utiliser les opérateurs conditionnels ifversion/else (ouifversion/elsif/else ) dans Markdown pour contrôler la façon dont le site affiche le contenu sur la page pour un produit particulier. Par exemple, une fonctionnalité peut avoir plus d'options sur GitHub.com que sur GitHub Enterprise Server, ce qui vous permet de versionner le contenu de manière appropriée via l'en-tête versions et d'utiliser des opérateurs conditionnels Liquid pour décrire les options supplémentaires pour GitHub.com.

Opérateurs de comparaison

Pour les versions qui n'ont pas de versions numérotées (telles que fpt et ghec), vous avez deux options :

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

Pour les versions qui ont des versions numérotées (actuellement uniquement ghes), vous pouvez faire de même pour le contenu disponible dans toutes les versions ou non disponible dans l'une des versions :

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

Si vous devez désigner du contenu uniquement disponible (ou non disponible) dans certaines versions, vous pouvez utiliser les opérateurs suivants :

Opérateur	Signification	Exemple
=	Égal à	{% ifversion ghes = 3.0 %}
>	Plus récent que	{% ifversion ghes > 3.0 %}
<	Antérieur à	{% ifversion ghes < 3.0 %}
!=	Non égal à	{% ifversion ghes != 3.0 %} (n'utilisez pas not dans les plages)

Les opérateurs Liquid ==, >= et <= ne sont pas pris en charge dans les GitHub Docs.

Opérateurs logiques

Lorsque tous les opérandes doivent avoir la valeur true pour que la condition soit true, utilisez l'opérateur and :

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

Lorsqu'au moins un opérande doit avoir la valeur true pour que la condition soit true, utilisez l'opérateur or :

{% ifversion fpt or ghes > 2.21 %}

N'utilisez pas les opérateurs && ou ||. Liquid ne les reconnaît pas et le contenu ne s'affiche pas dans les versions prévues.

Contrôle d'espace blanc

Lorsque vous utilisez des conditionnelles Liquid dans des listes, vous pouvez utiliser des caractères de contrôle de l'espace blanc pour empêcher l'ajout de nouvelles lignes et d'autres espaces blancs qui perturberaient le rendu de la liste.

Vous pouvez ajouter un trait d'union (-) sur la gauche, sur la droite ou sur les deux côtés pour indiquer qu'il ne doit pas y avoir de nouvelle ligne ou d'autre espace blanc sur ce côté.

{%- ifversion fpt %}

Par exemple, pour versionner une étape d'une procédure, plutôt que d'ajouter un versionnage Liquid pour l'étape commençant à la fin de l'étape précédente, telle que présentée ci-dessous :

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

Vous pouvez inclure le contrôle de version Liquid sur sa propre ligne et utiliser le contrôle d'espace blanc pour supprimer la nouvelle ligne à gauche de la balise Liquid. Cette démarche facilite grandement la lecture de la source, sans interrompre le rendu de la liste :

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

Contrôle de version basé sur les fonctionnalités

Lorsque vous documentez une nouvelle modification ou fonctionnalité, utilisez le contrôle de version basé sur les fonctionnalités.

Une petite minorité de fonctionnalités et de modifications ne s'appliqueront jamais qu'à un seul produit. La majorité des fonctionnalités sont fournies à GitHub.com et atteignent finalement tous les produits. En général, modifie le « flux » de GitHub.com (y compris GitHub Enterprise Cloud) en GitHub Enterprise Server, puis en .

Le contrôle de version basé sur les fonctionnalités fournit des « indicateurs de fonctionnalité » nommés qui simplifient la maintenance et le contrôle de version de la documentation. Vous pouvez utiliser un seul nom de fonctionnalité (ou « indicateur ») pour regrouper et contrôler la prose de tout le contenu. Lorsqu'une fonctionnalité arrive à des produits supplémentaires, il vous suffit d'apporter une modification au contrôle de version YAML dans le fichier dans data/features/.

Gestion des fonctionnalités

Chaque fonctionnalité est gérée via des fichiers YAML individuels dans data/features/.

Pour créer une fonctionnalité, commencez par créer un fichier YAML avec le nom de la fonctionnalité que vous souhaitez utiliser dans ce répertoire. Pour une fonctionnalité nommée meow, il s'agit de data/features/meow.yml.

Ajoutez un bloc versions au fichier YAML avec les noms courts des versions dans lesquelles la fonctionnalité est disponible. Par exemple :

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

Le format et les valeurs autorisées sont les mêmes que pour la propriété versions des informations préliminaires. Pour plus d'informations, consultez Versions dans le référentiel README github/docs.

Conditions liquides

Vous pouvez désormais utiliser {% ifversion meow %} ... {% endif %} dans les fichiers de contenu.

Informations préliminaires

Vous pouvez également utiliser la fonctionnalité dans les informations préliminaires des fichiers de contenu :

versions:
  feature: 'meow'

Vous ne pouvez utiliser qu'une entrée feature sous versions, et la valeur de feature ne peut contenir qu'un seul nom de fonctionnalité.

Vous pouvez combiner le contrôle de version basé sur les fonctionnalités et le contrôle de version standard dans les pages préliminaires. Lorsque vous effectuez cette opération, l'article est inclus dans le super-ensemble de toutes les versions spécifiées dans le fichier de contrôle de version basé sur les fonctionnalités et directement dans le fichier Markdown. Par exemple, vous pouvez avoir une fonctionnalité actuellement disponible uniquement dans GHEC, et elle est spécifiée dans le contrôle de version basé sur les fonctionnalités. Toutefois, vous souhaitez que l'article « À propos » de cette fonctionnalité soit également visible dans les documents FPT. Dans ce cas, vous pouvez ajouter fpt et feature au bloc versions dans les pages préliminaires :

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

Bonnes pratiques

Le contenu contrôlé a un impact sur le lecteur, mais aussi sur toute personne qui contribue au contenu ou l'examine. Voici quelques conseils pour améliorer l'expérience d'écriture, de lecture et de révision de la syntaxe de contrôle de version. Aucune de ces pratiques n'est obligatoire et vous trouverez des edge et corner cases, mais elles sont conçues comme des heuristiques utiles pour vous aider à réfléchir au contrôle de version.

Éviter le contrôle de version inutile

Pour le lecteur, il est plus important d'acquérir une compréhension générale que de lire des détails qui reflètent précisément les différences entre des produits ou des plans particuliers. Dans le contenu conceptuel ou procédural, essayez de décrire des fonctionnalités ou des parties de l'interface utilisateur d'une manière générale qui ne nécessite pas de syntaxe de contrôle de version. En plus d'être plus facile à gérer pour nous, cela renforce la compréhension pour les lecteurs qui font référence à la documentation de plusieurs produits.

• Demandez-vous : « Puis-je écrire ce contenu d'une manière qui s'applique à tous les produits sans contrôle de version ? »
• Essayez d'éviter les captures d'écran de contrôle de version si vous le pouvez, compte tenu de l'effort nécessaire pour les créer. Les différences mineures entre la copie de l'interface utilisateur peuvent ne pas affecter la compréhension. Si du texte ou des éléments d'interface utilisateur spécifiques au produit existent, mais que la capture d'écran fournit toujours un contexte utile, demandez-vous si le contrôle de version des captures d'écran affecterait la compréhension dans une mesure significative.
• Ne faites pas de prose de version si vous pouvez expliquer un concept ou guider le lecteur à travers une procédure sans contrôle de version pour des produits spécifiques.

Lors de la modification d'un fichier de contenu existant, passez en revue le contrôle de version existant plus tôt et souvent

Le fait de rester conscient du contrôle de version existant vous permet de vous assurer que vous écrivez des instructions de contrôle de version pertinentes et peut vous rappeler de contrôler le nouveau contenu avec précision.

• Passez en revue le contrôle de version de la page entière dans l'en-tête dès que vous commencez la modification.
• Examinez le contrôle de version autour du contenu que vous modifiez.
• Passez en revue la version affichée des modifications que vous apportez et basculez vers chaque version disponible pour la page dans le cadre de votre auto-révision.

Éviter la répétition autant que possible

Utilisez la syntaxe de contrôle de version dans une phrase ou un paragraphe pour différencier la prose de deux plans ou produits différents. Un contributeur ne peut modifier qu'un seul paragraphe avec des instructions de contrôle de version, au lieu d'avoir à prendre en compte des blocs plus volumineux de texte contrôlé et à modifier une prose similaire mais différemment contrôlée à deux endroits. Un réviseur peut suggérer une fois une modification, au lieu d'avoir à laisser la même suggestion à plusieurs endroits. Mais si le comportement diffère considérablement ou si le contrôle de version au sein de la phrase ou du paragraphe devient compliqué ou difficile à analyser pour un contributeur, envisagez de vous répéter pour rendre la prose plus facile à maintenir.

• Utilisez la syntaxe de contrôle de version inlined dans les paragraphes pour éviter de répéter des phrases ou des paragraphes entiers.

  Vous pouvez faire {% ifversion fpt %}quelque chose{% elsif ghec %}quelque chose d'autre{% endif %}.

• Utilisez votre jugement : pour la prose qui serait compliquée à écrire ou à lire sans beaucoup de syntaxe de contrôle de version au sein d'une phrase ou d'un paragraphe, envisagez de répéter le paragraphe entier dans un bloc de version pour chaque produit pertinent.

  {% ifversion fpt %}

  Si vous utilisez un plan Gratuit, Pro ou Team, vous pouvez faire quelque chose. Voici plus d'informations sur les choses que vous pouvez faire avec un plan Gratuit, Pro ou Team...

  {% elsif ghec %}

  Si vous utilisez GitHub Enterprise Cloud, vous pouvez faire autre chose. Voici plus d'informations sur les actions que vous pouvez effectuer avec GitHub Enterprise Cloud...

  {% endif %}

Être explicite, pas implicite

Si vous savez exactement quels produits le contenu décrit, contrôlez explicitement ces produits. Une syntaxe comme not et else en particulier, peut être imprécise. Le résultat final de not et else dépend de chaque en-tête d'article, donc un contributeur doit faire plus d'enquête pour comprendre la prose de ce contrôle de version. Cela crée un risque d'erreurs. La complexité du contrôle de version implicite augmente dans les réutilisables, où les articles qui font référence au réutilisable peuvent avoir un contrôle de version différent et donc des évaluations différentes de not ou else. Nous introduisons également occasionnellement une nouvelle version de GitHub Docs lorsque GitHub introduit un nouveau produit, ce qui modifie le résultat final de not et else lorsque nous ajoutons la nouvelle version à des articles existants.

• N'oubliez pas que GitHub propose quatre produits et n'oubliez pas que GitHub Docs peut afficher la documentation pour huit versions au total à tout moment.
• Examinez le contrôle de version d'un article entier dans l'en-tête, au début de la modification, car cela peut vous aider à comprendre comment not et else se comportent dans les instructions Liquid ou changent lorsque vous activez de nouvelles versions dans l'en-tête.

Vérifier et communiquer le contrôle de version à mesure que vous travaillez dans la conception et la création de contenu

Parfois, une modification n'est pas incluse dans la version pour laquelle elle a été initialement prévue. Vous pouvez gagner du temps pour les réviseurs et garantir un contenu plus précis en confirmant le contrôle de version tout au long de la conception et de la création du contenu, à la fois pour les mises en production et les améliorations.

• Envisagez le contrôle de version dans la conception de contenu et effectuez une double vérification du contrôle de version lorsque vous demandez des révisions des parties prenantes pour la création de contenu.
• Facilitez la révision pour les autres rédacteurs et parties prenantes : indiquez les différences entre les versions dans votre demande de révision, en les liant à des versions rendues spécifiques du contenu si nécessaire.
• Faire confiance mais vérifier

Tester, tester et tester à nouveau

Que vous écriviez le contenu ou que vous examiniez le contenu, faites attention au plan de conception de contenu et aux produits concernés et vérifiez le contenu affiché dans un environnement intermédiaire ou de développement pour vous assurer que le contenu décrit correctement chaque produit.