バージョン管理に関するドキュメント

GitHub Docs では、YAML frontmatter と liquid の演算子を使って、単一ソースのアプローチで複数のバージョンの GitHub をサポートします。

この記事の内容

GitHub Docs では、GitHub の主要な製品オファリング間の UI と機能の違いを反映したドキュメントのバージョンが提供されています。 共同作成者は、バージョン管理構文を使って、コンテンツのスコープを特定の製品オファリングに設定できます。

バージョン管理構文によって、使用している製品に該当するドキュメントのバージョンを読者が手動で選択できるようになります。 GitHub Docs の URL にバージョン情報を含めることもできます。これにより、GitHub Docs のあるバージョンから別のバージョンにリンクさせて、閲覧者が使用している製品のドキュメントに閲覧者を直接誘導できます。

バージョン管理を行う方法と場所

GitHub Docs のコンテンツのバージョン管理は、繰り返しを避け、文章の DRY を維持するために、単一ソースです。 記事の場合は、YAML メタデータを使って個々の Markdown ファイルにバージョン管理を適用し、ファイルの文章内で条件付きのステートメントを使って、読者が選択したバージョンに応じてどのテキストを表示するかをサイトに指示します。 単一ソースを使う方法は、コンテンツの各バージョンを反映した個別のファイルを作成する方法とは対照的です。

GitHub Docs には 2 種類のバージョン管理構文があります。

  • YAML: content/ の Markdown ファイル内の YAML front matter で最もよく使われますが、data/ の多くの種類の YAML ファイルでも使われます。 コンテンツ全体のバージョン管理を示します。

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

    次の例は、Free, Pro, & Team と GitHub Enterprise Server のすべてのバージョンに対してバージョン管理されたコンテンツを示しています。

    versions:
  fpt: *
  ghes: *

  • Liquid: content/ と data/reusables/ の Markdown ファイル内、data/variables/ の YAML ファイル内の変数文字列、または data/glossaries/external.yml 内の文字列で使われます。 YAML front matter によって複数のバージョンが定義されているコンテンツに対して読者がバージョンを選択したときに、表示するテキストを示します。

    • 製品ベースのバージョン管理:

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

    • 機能ベースのバージョン管理:

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

GitHub のさまざまなバージョンについて

GitHub Enterprise Cloud と GitHub Enterprise Server を含む GitHub プランのユーザー向けに、バージョン管理されたドキュメントが提供されています。 あるページのバージョンがサイト上に複数存在する場合、読者は、ページの上部にあるバージョン ピッカーからバージョンを選択できます。

GitHub.com

GitHub.com のドキュメントには、次の 2 つのバージョンが考えられます。

無料、Pro、またはチーム プラン

GitHub.com の無料、Pro、またはチーム プランの場合は、free-pro-team@latest を使います。 短い名前は fpt です。

GitHub Enterprise Cloud

GitHub Enterprise Cloud の場合は、enterprise-cloud@latest を使います。 短い名前は ghec です。

GitHub Enterprise Server

GitHub Enterprise Server のドキュメントには複数のバージョンがあり、2 つの種類に分けることができます。すなわち、サポートされているリリース のドキュメントと (同時に 4 つがサポートされます)、非推奨 のリリース のドキュメントです (Docs サイト上ではリンクされませんが、これらのドキュメントの "フリーズ" スナップショットは永続的にサポートされるため、URL がわかっていれば引き続きアクセスできます)。 一覧については lib/enterprise-server-releases.js を参照してください。

バージョンの名前は enterprise-server@<release> です。 短い名前は ghes です。 Liquid の条件では、ghes > 3.0 のように、範囲を指定できます。 詳しくは、「Liquid 条件付き演算子を使ったバージョン管理」を参照してください。

YAML frontmatter でのバージョン管理

ファイルの frontmatter 内で versions プロパティを使って、記事が表示される製品を定義できます。 インデックス ファイルには versions プロパティが必要ですが、子のバージョンに基づいて自動的にバージョン管理されます。

たとえば、次の YAML frontmatter では、GitHub Enterprise Server 2.20 以上と、無料、Pro、またはチームに対して記事がバージョン管理されます。

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

次の例では、GitHub Enterprise Server のサポートされているすべてのバージョンに対して記事がバージョン管理されます。

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

また、リリースの範囲に対してページをバージョン管理することもできます。 次の例では、Free, Pro, & Team、GitHub Enterprise Cloud、GitHub Enterprise Serverのバージョン 3.1 と 3.2 のみのページをバージョン管理します。

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

Liquid 条件付き演算子を使ったバージョン管理

Liquid テンプレート言語 (具体的には、こちらの Node.js ポート) とカスタム {% ifversion ... %} タグを使って、ドキュメントのバージョンを作成します。

ページの YAML frontmatter 内の versions キーで複数の製品を定義する場合は、Markdown の条件付き演算子 ifversion/else (または ifversion/elsif/else) を使って、特定の製品に対してサイトでページ上のコンテンツがレンダリングされる方法を制御できます。 たとえば、ある機能には GitHub Enterprise Server よりも GitHub.com の方が多くのオプションがある場合があります。その場合、versions frontmatter を使ってコンテンツを適切にバージョン管理し、Liquid の条件を使って GitHub.com 用の追加オプションを記述することができます。

注:

  • 製品ベースのバージョン管理と機能ベースのバージョン管理には、ifversion を使用してください。
  • if または unless を使用しないでください。
  • 必ず else if ではなく elsif を使ってください。 Liquid では else if は認識されず、else if ブロック内のコンテンツはレンダリングされません。

比較演算子

番号付きリリースがないバージョン (fpt や ghec など) の場合は、次の 2 つのオプションがあります。

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

番号付きリリースがあるバージョン (現在 ghes のみ) の場合、すべてのリリースで使用できるコンテンツ、またはどのリリースでも使用できないコンテンツに対して、同じ操作を実行できます。

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

特定のリリースでのみ使用できる (または使用できない) コンテンツを示す必要がある場合は、次の演算子を使用できます。

演算子意味例
=等しい{% ifversion ghes = 3.0 %}
>次より新しい{% ifversion ghes > 3.0 %}
<次より古い{% ifversion ghes < 3.0 %}
!=等しくない{% ifversion ghes != 3.0 %} (範囲では not を使用しないでください)

Liquid 演算子 ==、>=、<= は、GitHub Docs ではサポートされていません。

論理演算子

条件が true になるにはすべてのオペランドが true になる必要がある場合は、and 演算子を使います。

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

条件が true になるには少なくとも 1 つのオペランドが true になる必要がある場合は、or 演算子を使います。

{% ifversion fpt or ghes > 2.21 %}

演算子 && または || は使用しないでください。 Liquid ではそれらが認識されず、目的のバージョンではコンテンツがレンダリングされません。

空白コントロール

リストで Liquid 条件を使用する際、空白コントロール文字を使用して、リストの表示を崩す改行やその他の空白文字の追加を防ぐことができます。

左、右、または両側にハイフン (-) を追加して、その位置に改行やその他の空白が存在すべきではないことを示すことができます。

{%- ifversion fpt %}

たとえば、手順の 1 ステップをバージョン管理するには、前のステッの末尾から始まるステップの liquid バージョン管理を追加するのではなく、以下のように行います。

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

liquid バージョン管理をそれ自体の行に含め、空白コントロールを使用して、liquid タグの左側にある改行を削除できます。 こうすると、リストのレンダリングが崩れず、ソースの読み取りがはるかに簡単になります。

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

機能ベースのバージョン管理について

新しい変更または機能を文書化するときは、機能ベースのバージョン管理を使います。

1 つの製品にしか適用されない機能や変更は、ごく少数だけです。 ほとんどの機能は GitHub.com に達し、最終的にすべての製品に到達します。 一般に、変更は GitHub.com (GitHub Enterprise Cloud を含む) から GitHub Enterprise Server に "フロー" します。

機能ベースのバージョン管理では、ドキュメントのメンテナンスとバージョン管理を簡素化する、名前付き "機能フラグ" が提供されます。 1 つの機能名 (または "フラグ") を使って、コンテンツ全体で文章をグループ化およびバージョン管理できます。 追加の製品に機能が導入される場合は、data/features/ 内のファイルの YAML バージョン管理を変更するだけで済みます。

機能の管理

各機能は、data/features/ 内の個々の YAML ファイルを使って管理されます。

注: data/features/placeholder.yml はテストで使用されるため、削除しないでください。

新しい機能を作成するには、まず、このディレクトリに使いたい機能名を持つ新しい YAML ファイルを作成します。 meow という名前の機能の場合、data/features/meow.yml のようになります。

YAML ファイルに、その機能を利用できる各バージョンの短い名前を含む versions ブロックを追加します。 次に例を示します。

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

書式と許可される値は、frontmatter versions プロパティと同じです。 詳しくは、github/docs リポジトリの README の「versions」を参照してください。

Liquid の条件

これで、コンテンツ ファイルで {% ifversion meow %} ... {% endif %} を使用できるようになりました。

frontmatter

コンテンツ ファイルの frontmatter でこの機能を使用することもできます。

versions:
  feature: 'meow'

versions の下に使用できる feature エントリは 1 つだけです。また、feature の値には 1 つの機能名のみを含めることができます。

frontmatter では、機能ベースのバージョン管理と標準バージョン管理を組み合わせることができます。 この操作を行うと、この記事は、機能ベースのバージョン管理ファイルで指定されたすべてのバージョンのスーパーセットと、Markdown ファイルに直接含まれます。 たとえば、現在 GHEC でのみ使用できる機能があるとき、これは機能ベースのバージョン管理で指定されている場合があります。 ただし、この機能の "バージョン情報" に関する記事も FPT ドキュメントに表示する必要があります。この場合、前付の fpt ブロックに feature と versions を追加できます。

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

ベスト プラクティス

バージョン管理されたコンテンツは読者に影響を与えますが、コンテンツを投稿またはレビューするすべてのユーザーにも影響を与えます。 バージョン管理構文の記述、読み取り、レビューのエクスペリエンスを向上させるためのヒントをいくつか次に示します。 これらのプラクティスはいずれも必須ではなく、特殊なケースが記載されていますが、バージョン管理について熟考するのに役立つ便利なヒューリスティックになることを目的としています。

不要なバージョン管理を避ける

読者にとっては、一般的な理解を得ることが、特定の製品やプランの違いを正確に反映した詳細情報を読むことよりも重要です。 概念的または手続き的なコンテンツの場合は、バージョン管理構文を必要としない一般的な方法で機能や UI の部分を記述してみてください。 こうすることで、保守が容易になるだけでなく、複数の製品についてドキュメントを参照する読者の理解も深まります。

  • 「このコンテンツは、バージョン管理なしですべての製品に当てはまる方法で記述できるか」と自問してください。
  • スクリーンショットのバージョン管理は、その作成に必要な作業を考慮して、可能であれば避けるようにしてください。 UI のコピー間の小さな違いは、理解に影響を与えない可能性があります。 製品固有のテキストや UI 要素が存在するが、スクリーンショットによって役立つコンテキストが提供される場合は、スクリーンショットのバージョン管理が理解に重要な影響を与えるかどうかを自問してください。
  • 特定の製品のバージョン管理を行わなくても、概念を説明したり、読者に手順を一通り説明したりできる場合は、文章をバージョン管理しないでください。

既存のコンテンツ ファイルを変更するときは、既存のバージョン管理を早期かつ頻繁に確認する

既存のバージョン管理を常に認識しておくことは、関連するバージョン管理ステートメントを確実に記述するのに役立ち、忘れずに新しいコンテンツを正確にバージョン管理するのにも役立ちます。

  • 編集を開始したらすぐに、front matter でページ全体のバージョン管理を確認してください。
  • 編集しているコンテンツに関するバージョン管理を確認してください。
  • 行っている変更のレンダリングされたバージョンを確認し、自己レビューの一環としてページの使用できる各バージョンに切り替えてください。

可能な限り繰り返しを避ける

文または段落内でバージョン管理構文を使い、2 つの異なるプランまたは製品用に文章を分けます。 共同作成者は、バージョン管理ステートメントを使って 1 つの段落のみを編集できるため、バージョン管理されたテキストの大きなブロックを考慮し、似ているがバージョンが異なる 2 か所の文章を変更する必要がなくなります。 レビュー担当者は変更を 1 回提案すればよく、同じ提案を複数の場所に残す必要はありません。 しかし、動作が劇的に異なる場合や、文または段落内のバージョン管理が複雑になったり、共同作成者が解析するのが困難になったりする場合は、繰り返しの作業を行って文章を維持しやすくすることを検討してください。

  • 段落内でバージョン管理構文をインラインで使い、文や段落全体の繰り返しを避けてください。

    {% ifversion fpt %}何か{% elsif ghec %}別の何か{% endif %}を実行できます。

  • ご自身で判断してください: 文や段落内で多くのバージョン管理構文なしで書いたり読んだりするのが複雑になる文章については、関連する製品ごとにバージョン ブロック内の段落全体を繰り返すことを検討してください。

    {% ifversion fpt %}

    無料、Pro、またはチーム プランを使用している場合は、何かを実行できます。 無料、Pro、またはチーム プランで実行できる操作の詳細をここに記述します...

    {% elsif ghec %}

    GitHub Enterprise Cloud を使用している場合は、他の操作を実行できます。 GitHub Enterprise Cloud で実行できる操作の詳細をここに記述します...

    {% endif %}

暗黙的ではなく明示的にする

コンテンツで記述する製品が正確にわかっている場合は、それらの製品に対して明示的にバージョンを指定します。 not や、特に else のような構文は、不正確になる場合があります。 not と else の最終的な結果は各記事の front matter に依存するため、共同作成者はさらに調査を行って、このバージョン管理での文章を理解する必要があります。 これにより、エラーが発生する可能性があります。 再利用では、暗黙的なバージョン管理はますます複雑になります。再利用を参照する記事のバージョン管理が異なるため、not や else の評価も異なる可能性があります。 また、GitHub で新しい製品が導入されるときに、GitHub Docs に新しいバージョンが導入されることもあります。これにより、既存の記事に新しいバージョンが追加されると、not と else の最終的な結果が変わります。

  • GitHub では 4 つの製品が提供されていることを忘れないでください。また、GitHub Docs では、いつでも合計 8 つのバージョンのドキュメントを表示できることを忘れないでください。
  • 編集を開始するときは、front matter で記事全体のバージョン管理を確認してください。これは、Liquid ステートメントでの not と else の動作を理解したり、front matter で新しいバージョンを有効にするときに変更したりするのに役立ちます。

コンテンツの設計と作成を行う際にバージョン管理を確認して伝達する

変更が、最初に意図されていたリリースに含まれない場合があります。 リリースと改善の両方について、コンテンツの設計と作成全体でバージョン管理を確認することで、レビュー担当者の時間を節約し、より正確なコンテンツを確実に作成することができます。

  • コンテンツの設計時にバージョン管理を考慮し、利害関係者にコンテンツ作成のレビューを要求するときにバージョン管理を再確認してください。
  • 他の書き手や利害関係者がレビューしやすいようにしてください: レビューの要求でバージョン間の違いを指摘し、必要に応じて特定のレンダリングされたバージョンのコンテンツにリンクしてください。
  • 信頼するが、検証してください。

テスト、テスト、またテスト

コンテンツを作成する場合も、コンテンツをレビューする場合も、コンテンツの設計計画と影響を受ける製品に注意を払い、ステージング環境または開発環境でレンダリングされたコンテンツをチェックして、コンテンツが各製品を正確に記述していることを確認してください。