機能フラグの背後にデプロイされた機能を文書化

GitLabは機能フラグを使って独自の機能をデプロイしています。

機能フラグの状態が変わったら、変更を行った開発者はドキュメントを更新しなければなりません。

機能フラグの背後にある機能を文書化するとき

コードベースに導入されたすべての機能は、たとえそれが無効化された機能フラグの後ろにあっても、ドキュメント化されなければなりません。詳しくは、この決定に至った議論をご覧ください。実験版やベータ版の機能は通常機能フラグの後ろにあり、ドキュメント化されなければなりません。詳しくは、Document Experiment or Beta featuresをご覧ください。

その機能が複数のマージリクエストで実装される場合、テクニカルライターとその計画について議論してください。

その機能が実装された場合、ドキュメンテーションイシューを作成し、ドキュメンテーションを遅らせることができます：

  • ナビゲーションの変更のように、広範囲に及ぶ（GitLabの多くの領域に変更を加える）場合。
  • 多くのMRを含みます。
  • 数ページ以上のドキュメントに影響します。
  • テストのために機能フラグを有効にした場合、完全に機能しません。

PM、EM、ライターは、ドキュメンテーション作業が割り当てられ、スケジュールされていることを確認する必要があります。

コードベースにあるすべての機能フラグは、たとえその機能が完全でない場合であっても、あるいは他の方法で文書化されていない場合であっても、文書化されます。

機能フラグドキュメントの追加方法

機能フラグを文書化する場合、次のことが必要です：

バージョン履歴テキストの追加

フラグの状態が変更された場合 (例えば、デフォルトで無効→デフォルトで有効)、その変更をバージョン履歴に追加します。

可能なバージョン履歴エントリは以下のとおりです：

> - [Introduced](issue-link) in GitLab X.X [with a flag](../../administration/feature_flags.md) named `flag_name`. Disabled by default.
> - [Enabled on GitLab.com](issue-link) in GitLab X.X.
> - [Enabled on GitLab.com](issue-link) in GitLab X.X. Available to GitLab.com administrators only.
> - [Enabled on self-managed](issue-link) in GitLab X.X.
> - [Generally available](issue-link) in GitLab X.Y. Feature flag `flag_name` removed.

機能フラグの状態を説明するノートを使用します。

機能フラグに関する情報は、トピックの冒頭 (バージョン履歴のすぐ下) にあるFLAG のノートに記述してください。

ノートには3つの部分があり、以下のような構成になっています：

FLAG:
<Self-managed GitLab availability information.>
<GitLab.com availability information.>
<This feature is not ready for production use.>

FLAG のノートは、GitLab ドキュメントサイトでは次のように表示されます：

フラグ: セルフマネジメントのGitLabでは、デフォルトではこの機能は利用できません。利用可能にするには、管理者がexample_flagという機能フラグを有効にします。GitLab.comでは、この機能は利用できません。この機能はまだ本番環境では使用できません。

セルフマネジメントGitLabの可用性情報

もしその機能が…このテキストを使用
利用可能On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.
利用不可On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.
一部のユーザーは利用可能On self-managed GitLab, by default this feature is available to a subset of users. To show or hide the feature for all, an administrator can [change the status of the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.
グループ単位で利用可能On self-managed GitLab, by default this feature is available. To hide the feature per group, an administrator can [disable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.
利用不可、グループ毎On self-managed GitLab, by default this feature is not available. To make it available per group, an administrator can [enable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.
プロジェクト単位で利用可能On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, an administrator can [disable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.
利用不可、プロジェクトごとOn self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.
ユーザー単位で利用可能On self-managed GitLab, by default this feature is available. To hide the feature per user, an administrator can [disable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.
利用不可、ユーザー毎On self-managed GitLab, by default this feature is not available. To make it available per user, an administrator can [enable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.

GitLab.comの可用性情報

もしその機能が…このテキストを使用
利用可能On GitLab.com, this feature is available.
GitLab.com管理者のみ利用可能On GitLab.com, this feature is available but can be configured by GitLab.com administrators only.
利用不可On GitLab.com, this feature is not available.

オプション情報

必要に応じて、この文章を追加することができます：

The feature is not ready for production use.

機能フラグドキュメントの例

以下の例は、機能フラグの進行を示しています。

> Introduced in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.

FLAG:
On self-managed GitLab, by default this feature is not available. To make it available,
an administrator can [enable the feature flag](../administration/feature_flags.md) named `forti_token_cloud`.
The feature is not ready for production use.

本番環境で機能が有効になると、バージョン履歴を更新できます：

> - Introduced in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.
> - [Enabled on self-managed](https://gitlab.com/issue/etc) GitLab 13.8.

FLAG:
On self-managed GitLab, by default this feature is available. To hide the feature per user,
an administrator can [disable the feature flag](../administration/feature_flags.md) named `forti_token_cloud`.

そして、その機能が完了し、すべてのユーザーが完全に利用できるようになったとき：

> - Introduced in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.
> - [Enabled on self-managed](https://gitlab.com/issue/etc) in GitLab 13.8.
> - [Enabled on GitLab.com](https://gitlab.com/issue/etc) in GitLab 13.9.
> - [Generally available](issue-link) in GitLab 14.0. Feature flag `forti_token_cloud` removed.

長いバージョン履歴の簡素化

バージョン履歴は長くなることがありますが、エントリを簡略化したり削除したりすることができます。

同じリリースで起こったことであれば、エントリを統合してください：

  • 前

     > - [Introduced](issue-link) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default.
 > - [Enabled on GitLab.com](issue-link) in GitLab 14.3.
 > - [Enabled on self-managed](issue-link) in GitLab 14.3.

  • After

     > - [Introduced](issue-link) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default.
 > - [Enabled on GitLab.com and self-managed](issue-link) in GitLab 14.3.

GitLab.comと自己管理の両方でデフォルトで機能が有効になっている場合、Enabled on GitLab.com エントリを削除します：

  • 前

     > - [Introduced](issue-link) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default.
 > - [Enabled on GitLab.com](issue-link) in GitLab 15.9.
 > - [Generally available](issue-link) in GitLab 15.10. Feature flag `ci_hooks_pre_get_sources_script` removed.

  • After

     > - [Introduced](issue-link) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default.
 > - [Generally available](issue-link) in GitLab 15.10. Feature flag `ci_hooks_pre_get_sources_script` removed.