Dokumentation zur Versionierung

In GitHub Docs stellen wir Versionen unserer Dokumentation bereit, die die Unterschiede bei Benutzeroberfläche und Funktionalität der wichtigsten GitHub-Produktangebote verdeutlichen. Mitwirkende können eine Versionierungssyntax verwenden, um Inhalte auf ein bestimmtes Produktangebot zu beschränken.

Dank dieser Syntax können Leserinnen manuell die Version der Dokumentation auswählen, die für das verwendete Produkt gilt. Die URLs von GitHub Docs können ebenfalls Versionsinformationen enthalten, sodass Links von GitHub.com und GitHub Enterprise Server die Leserinnen direkt zur Dokumentation für das verwendete Produkt weiterleiten.

Versionierung – wie und wo?

Die Versionierung für Inhalte in GitHub Docs basiert auf einer einzigen Quelle, um Wiederholungen zu vermeiden und dem DRY-Prinzip zu folgen. Bei Artikeln wenden Sie die Versionierung auf eine einzelne Markdowndatei mit YAML-Metadaten an. Dann verwenden Sie Bedingungsanweisungen im Text der Datei, um die Website anzuweisen, welcher Text je nach ausgewählter Version angezeigt werden soll. Single-Sourcing steht im Gegensatz zur Erstellung separater Dateien, die die einzelnen Versionen des Inhalts widerspiegeln.

Es gibt zwei Arten von Versionierungssyntax für GitHub Docs.

• YAML: Wird am häufigsten in der YAML-Titelei in Markdowndateien in content/, aber auch in vielen YAML-Dateitypen in data/ verwendet. Gibt die Versionierung für einen gesamten Inhalt an.

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

  Das folgende Beispiel zeigt Inhalte mit Versionierung für GitHub.com und alle Versionen von GitHub Enterprise Server.

  versions:
    fpt: *
    ghes: *
  

• Liquid: Wird in Markdowndateien in content/ und data/reusables/, variablen Zeichenfolgen in YAML-Dateien in data/variables/ oder Zeichenfolgen in data/glossaries/external.yml verwendet. Gibt an, welcher Text angezeigt werden soll, wenn Leser*innen eine Version für Inhalte auswählen, für die von der YAML-Titelei mehrere Versionen definiert wurden.

  • Produktbasierte Versionierung:

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

  • Featurebasierte Versionierung:

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

Informationen zu den verschiedenen Versionen von GitHub

Für Benutzerinnen mit GitHub.com-Plänen, einschließlich GitHub Enterprise Cloud und GitHub Enterprise Server, stellen wir eine versionsbasierte Dokumentation bereit. Wenn mehrere Versionen einer Seite auf der Website vorhanden sind, können Leserinnen mithilfe der Versionsauswahl oben auf der Seite die gewünschte Version auswählen.

GitHub.com

Die Dokumentation für GitHub.com hat zwei mögliche Versionen:

Free-, Pro- oder Team-Pläne

Verwenden Sie free-pro-team@latest für Free-, Pro- oder Team-Pläne auf GitHub.com. Der Kurzname lautet fpt.

GitHub Enterprise Cloud

Verwenden Sie enterprise-cloud@latest für GitHub Enterprise Cloud. Der Kurzname lautet ghec.

GitHub Enterprise Server

Die Dokumentation für GitHub Enterprise Server steht in mehreren Versionen bereit und kann in zwei Arten unterteilt werden: Dokumentation für unterstützte Versionen (wir unterstützen vier gleichzeitig) und Dokumentation für veraltete Versionen (wir verknüpfen diese nicht auf der Docs-Website, aber wir unterstützen dauerhaft eine „eingefrorene“ Momentaufnahme dieser Dokumente, sodass der Zugriff weiterhin möglich ist, wenn Sie die URLs kennen). Eine Liste finden Sie unter lib/enterprise-server-releases.js.

Die Versionen heißen enterprise-server@<release>. Der Kurzname lautet ghes. Für Liquid-Bedingungen können wir Bereich angeben, z. B. ghes > 3.0. Weitere Informationen finden Sie unterVersionierung mit Liquid-Bedingungsoperatoren.

Versionierung in der YAML-Titelei

Sie können die versions-Eigenschaft im Frontmatter einer Datei verwenden, um festzulegen, für welche Produkte ein Artikel erscheinen soll. Indexdateien erfordern eine versions-Eigenschaft, aber sie werden automatisch basierend auf den Versionen ihrer untergeordneten Elemente versioniert.

Beispielsweise verwaltet die folgende YAML-Titelei die Versionen eines Artikels für GitHub Enterprise Server 2.20 und höher sowie Free, Pro oder Team.

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

Das folgende Beispiel verwaltet alle unterstützten Versionen von GitHub Enterprise Server für einen Artikel:

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

Sie können für eine Seite auch einen versionsspezifischen Releasebereich festlegen. Das folgende Beispiel verwaltet die Versionen der Seite nur für GitHub.com und die GitHub Enterprise Server-Versionen 3.1 und 3.2:

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

Versionierung mit Liquid-Bedingungsoperatoren

Wir verwenden die Vorlagensprache Liquid (insbesondere diesen Node.js Port) und ein benutzerdefiniertes {% ifversion ... %}-Tag, um Versionen unserer Dokumentation zu erstellen.

Wenn Sie im versions-Schlüssel der YAML-Titelei für eine Seite mehrere Produkte definieren, können Sie die Bedingungsoperatoren ifversion``else/ (oder ifversion/elsif/) im Markdown verwenden, um zu steuern, wie die Website Inhalte auf der Seite für ein bestimmtes Produkt rendert. Beispielsweise verfügt ein Feature möglicherweise über mehr Optionen für GitHub.com als für GitHub Enterprise Server, sodass Sie den Inhalt über die versions-Titelei entsprechend versionieren und Liquid-Bedingungen verwenden können, um die zusätzlichen Optionen für GitHub.com zu beschreiben.

Vergleichsoperatoren

Bei Versionen ohne nummerierte Releases (z. B. fpt und ghec) stehen dir zwei Optionen zur Verfügung:

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

Bei Versionen mit nummerierten Releases (derzeit nur ghes) können Sie dasselbe für Inhalte verwenden, die entweder in allen Releases verfügbar oder in allen Releases nicht verfügbar sind:

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

Wenn Sie Inhalte angeben müssen, die nur in bestimmten Releases verfügbar (oder nicht verfügbar) sind, können Sie die folgenden Operatoren verwenden:

Operator	Bedeutung	Beispiel
=	Gleich	{% ifversion ghes = 3.0 %}
>	Neuer als	{% ifversion ghes > 3.0 %}
<	Älter als	{% ifversion ghes < 3.0 %}
!=	Ungleich	{% ifversion ghes != 3.0 %} (verwenden Sie not nicht in Bereichen)

Die Liquid-Operatoren ==, >= und <= werden in GitHub Docs nicht unterstützt.

Logische Operatoren

Wenn alle Operanden „true“ sein müssen, damit die Bedingung als „true“ ausgewertet wird, verwenden Sie den Operator and:

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

Wenn mindestens ein Operand „true“ sein muss, damit die Bedingung als „true“ ausgewertet wird, verwenden Sie den Operator or:

{% ifversion fpt or ghes > 2.21 %}

Verwenden Sie nicht die Operatoren && oder ||. Liquid erkennt sie nicht, und der Inhalt wird nicht in den vorgesehenen Versionen gerendert.

Steuern von Leerräumen

Wenn Sie Liquid-Bedingungen in Listen verwenden, können Sie mit Zeichen zur Steuerung von Leerräumen verhindern, dass Zeilenvorschübe und andere Leerräume eingefügt werden, die das korrekte Rendern der Liste verhindern.

Fügen Sie hierfür links, rechts oder an beiden Seiten einen Bindestrich (-) hinzu, um an dieser Stelle einen Zeilenvorschub oder anderen Leerraum zu verhindern.

{%- ifversion fpt %}

Wenn Sie z. B. einen Schritt einer Prozedur versionieren möchten, anstatt die Liquid-Versionsverwaltung für den Schritt hinzuzufügen, der am Ende der vorherigen Schritts beginnt, gehen Sie wie folgt vor:

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

Sie können die Liquid-Versionsverwaltung in eine eigene Zeile aufnehmen und das whitespace-Steuerelement verwenden, um die neue Zeile links neben dem Liqid-Tag abzuschneiden. Dadurch wird das Lesen der Quelle wesentlich einfacher, ohne das Rendern der Liste zu unterbrechen:

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

Informationen zur featurebasierten Versionierung

Wenn Sie Änderungen oder neue Features dokumentieren, verwenden Sie die featurebasierte Versionierung.

Es gibt nur wenige Features und Änderungen, die jeweils nur für ein Produkt gelten. Die meisten Features gelangen auf GitHub.com und letztendlich in alle Produkte. Im Allgemeinen werden Änderungen von GitHub.com (einschließlich GitHub Enterprise Cloud) an GitHub Enterprise Server weitergegeben.

Die featurebasierte Versionierung bietet benannte „Featureflags“, die die Wartung und Versionierung der Dokumentation vereinfachen. Sie können einen einzelnen Featurenamen (ein „Flag“) verwenden, um Text im gesamten Inhalt zu gruppieren und zu versionieren. Wenn ein Feature in weiteren Produkten verwendet wird, müssen Sie nur die YAML-Versionierung in der Datei in data/features/ ändern.

Verwalten von Features

Alle Features werden über einzelne YAML-Dateien in data/features/ verwaltet.

Fügen Sie eine neue YAML-Datei mit dem Featurenamen hinzu, den Sie in diesem Verzeichnis verwenden möchten. Für ein Feature mit dem Namen meow wäre das data/features/meow.yml.

Fügen Sie der YML-Datei einen Block versions hinzu, in dem die Kurznamen der Versionen verfügbar sind, in der das Feature verfügbar ist. Zum Beispiel:

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

Das Format und die zulässigen Werte entsprechen der Frontmatter-Versionseigenschaft. Weitere Informationen finden Sie in der Infodatei für die Integration im Repository github/docs.

Flüssigkeitsbedingte Bedingungen

Jetzt können Sie {% ifversion meow %} ... {% endif %} in Inhaltsdateien verwenden!

Frontmatter

Sie können das Feature auch im Frontmatter in Inhaltsdateien verwenden:

versions:
  feature: 'meow'

Du kannst nur einen feature-Eintrag unter versionsverwenden, und der Wert von feature darf nur einen Featurenamen enthalten.

Du kannst featurebasierte Versionsverwaltung und Standardversionsverwaltung im Frontmatter kombinieren. Wenn du dies tust, wird der Artikel in die Obermenge aller Versionen aufgenommen, die in der featurebasierten Versionsverwaltungsdatei und direkt in der Markdown-Datei angegeben sind. Beispielsweise verfügst du möglicherweise über ein Feature, das derzeit nur in GHEC verfügbar ist, und dies wird in der featurebasierten Versionsverwaltung angegeben. Du möchtest jedoch, dass der Artikel „Info“ für dieses Feature auch in den FPT-Dokumenten sichtbar sein soll. In diesem Fall könntest du dem versions-Block im Vordergrund fpt und feature hinzufügen:

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

Bewährte Methoden

Inhalte mit Versionierung betreffen nicht nur die Leser*innen, sondern alle Personen, die zu Inhalten beitragen oder diese überprüfen. Hier finden Sie einige Tipps zum Verbessern der Schreib-, Lese- und Überprüfungsprozesse für die Versionierungssyntax. Keine dieser Methoden ist obligatorisch, und es wird immer Sonder- und Grenzfälle geben, aber sie sind als nützliche Heuristik gedacht, um Sie bei der Versionierung zu unterstützen.

Unnötige Versionierung vermeiden

Für die Leserinnen ist es wichtiger, ein allgemeines Verständnis der Produkte und Pläne zu erlangen, als Details zu den genauen Unterschieden zwischen bestimmten Produkten oder Plänen zu lesen. Bei konzept- oder prozedurbezogenen Inhalten sollten Sie versuchen, Features oder Teile der Benutzeroberfläche allgemein zu beschreiben, sodass keine Versionssyntax erforderlich ist. Dies erleichtert einerseits uns die Verwaltung und verbessert andererseits das Verständnis der Leserinnen, die die Dokumentation für verschiedene Produkte zu Rate ziehen.

• Stell dir diese Frage: „Kann ich diesen Inhalt auf eine Weise schreiben, dass er ohne Versionierung auf alle Produkte zutrifft?“
• Da das Erstellen von Screenshots mit nicht geringem Aufwand verbunden ist, versuche nach Möglichkeit, versionsbezogene Screenshots zu vermeiden. Geringfügige Unterschiede zwischen den Benutzeroberflächen beeinträchtigen das allgemeine Verständnis oft nicht. Wenn es produktspezifische Text- oder Benutzeroberflächenelemente gibt, der Screenshot aber dennoch hilfreichen Kontext bietet, stell dir die Frage, ob ein versionsbezogener Screenshot das Verständnis wesentlich beeinträchtigen würde.
• Verwenden Sie keine Versionsangaben, wenn Sie ein Konzept erläutern oder Leser*innen durch ein Verfahren führen können, ohne bestimmte Produktversionen zu erwähnen.

Beim Ändern einer vorhandenen Inhaltsdatei vorhandene Versionen frühzeitig und häufig überprüfen

Wenn Sie sich stets bewusst machen, dass verschiedene Versionen vorhanden sind, können Sie relevante Versionsinformationen erstellen und neue Inhalte korrekt versionieren.

• Bevor Sie mit einer Bearbeitung beginnen, sehen Sie sich die Versionierung der gesamten Seite in der Titelei an.
• Überprüfen Sie die Versionierung rund um die Inhalte, die Sie bearbeiten.
• Überprüfen Sie die gerenderte Version der von dir vorgenommenen Änderungen, und wechsle im Rahmen der Selbstüberprüfung zu jeder verfügbaren Version für die Seite.

Wiederholungen so weit wie möglich vermeiden

Verwenden Sie die Versionierungssyntax innerhalb eines Satzes oder Absatzes, um zwischen den Texten für zwei verschiedene Pläne oder Produkte zu unterscheiden. Mithilfe von Versionierungsanweisungen können Beitragende nur einen Absatz bearbeiten und müssen keine größeren Blöcke mit versioniertem Text berücksichtigen. So können sie ähnliche, aber nicht exakt gleiche Versionstexte an zwei Stellen bearbeiten. Reviewer können Änderungen nur einmal vorschlagen und müssen ihre Vorschläge nicht an mehreren Stellen einbringen. Wenn sich Verhaltensweisen jedoch erheblich unterscheiden oder die Versionierung in einem Satz oder Absatz so kompliziert oder schwierig wird, dass sie von Beitragenden kaum analysiert werden kann, sollten Sie sich wiederholen, damit die Texte einfacher zu verwalten sind.

• Verwenden Sie die Versionierungssyntax inline innerhalb von Absätzen, um zu vermeiden, dass sich Sätze oder ganze Absätze wiederholen.

  Sie können {% ifversion fpt %}etwas{% elsif ghec %}etwas anderes{% endif %} tun.

• Nutzen Sie Ihr Urteilsvermögen: Wenn Inhalte ohne Versionierungssyntax in einem Satz oder Absatz nur schwer zu schreiben oder zu lesen wären, sollten Sie erwägen, den gesamten Absatz in einem Versionsblock für jedes betreffende Produkt zu wiederholen.

  {% ifversion fpt %}

  Wenn Sie einen Free-, Pro- oder Team-Plan nutzt, können Sie etwas tun. Hier finden Sie weitere Informationen dazu, was Sie mit einem Free-, Pro- oder Team-Plan tun können: ...

  {% elsif ghec %}

  Wenn Sie GitHub Enterprise Cloud verwenden, können Sie etwas anderes tun. Hier finden Sie weitere Informationen dazu, was Sie mit GitHub Enterprise Cloud tun können: ...

  {% endif %}

Explizite Angaben verwenden

Wenn Sie genau wissen, welche Produkte durch den Inhalt beschrieben werden, verwenden Sie die expliziten Versionen für diese Produkte. Ein Syntax wie not und else kann ungenau sein. Das Endergebnis von not und else hängt von der Titelei jedes Artikels ab, sodass Beitragende mehr suchen muss, um Texte mit einer solchen Versionierung zu verstehen. Dadurch entsteht Fehlerpotenzial. Die Komplexität einer impliziten Versionierung nimmt bei wiederverwendbaren Textbausteinen noch weiter zu, da bei Artikeln, die auf solche Bausteine verweisen, eine andere Versionierung verwendet worden sein kann, sodass not oder else unterschiedlich ausgewertet werden. Wir führen gelegentlich auch eine neue Version in GitHub Docs ein, wenn GitHub ein neues Produkt einführt, wodurch sich das Ergebnis von not und else ändert, wenn wir die neue Version zu vorhandenen Artikeln hinzufügen.

• Denk daran, dass GitHub vier Produkte anbietet, und denk auch daran, dass GitHub Docs die Dokumentation für insgesamt acht Versionen anzeigen kann.
• Bevor Sie mit einer Bearbeitung beginnen, sehen Sei sich die Versionierung der gesamten Seite in der Titelei an. So können Sie besser verstehen, wie sich not und else in Liquid-Anweisungen verhalten oder ändern, wenn Sie neue Versionen in der Titelei aktivieren.

Überprüfen und kommunizieren Sie die Versionierung, während Sie Inhalte entwerfen und erstellen.

Manchmal ist eine Änderung nicht in dem Release enthalten, für das sie ursprünglich vorgesehen war. Sie können Prüfer*innen Zeit sparen und die Richtigkeit der Inhalte sicherstellen, indem Sie die Versionierung im gesamten Entwurfs- und Erstellungsprozess überprüfen – sowohl für Releases als auch für Verbesserungen.

• Berücksichtigen Sie die Versionierung im Inhaltsentwurf, und überprüfen Sie sie, wenn Sie vor der endgültigen Inhaltserstellung ein Review durch Projektbeteiligte anfordernde Person.
• Gestalten Sie den Prüfprozess für andere Verfasser*innen und Beteiligte einfacher: Weise in der Überprüfungsanforderung auf Unterschiede zwischen den Versionen hin, und fügen Sie ggf. Links zu bestimmten gerenderten Versionen des Inhalts hinzu.
• Vertrauen ist gut – Kontrolle ist besser.

Testen, testen und nochmals testen

Egal, ob Sie Inhalte schreiben oder überprüfen – achten Sie auf den Plan für den Inhaltsentwurf und die betroffenen Produkte. Überprüfen Sie den gerenderten Inhalt in einer Staging- oder Entwicklungsumgebung, um sicherzustellen, dass jedes Produkt präzise und korrekt beschrieben wird.