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

GitLab はフィーチャーフラグを使って、独自の機能のデプロイを戦略的に行っています。 フィーチャーフラグの背後にある機能のドキュメントの書き方は、その状態 (有効か無効か) に依存します。 状態が変わったら、変更を行った開発者はそれに応じてドキュメントを更新しなければなりません。

基準

フィーチャーフラグの背後にあるGitLab機能のデプロイプロセスに従います：

  • デフォルトでは、機能フラグはオフになっているはずです。
  • フィーチャーフラグは、フィーチャーフラグのアカウンティングの必要性を減らすために、できるだけ短期間コードベースに残すべきです。
  • 最終リリースをビルドし、セルフマネージドユーザーに機能を提供するためには、機能フラグを少なくともデフォルトでオンにする必要があります。

国旗の状態に応じた記録方法を以下でご覧ください：

注**(CORE ONLY)**機能フラグの有効化/無効化には管理者権限が必要なため、GitLab.com の一般ユーザーでは行えないことを示すために、機能フラグを有効化/無効化する行と見出しには、その機能の階層に対応するバッジまたは同等のバッジを追加してください。

デフォルトで無効になっている機能

デフォルトで無効になっている機能については、完全性がないためにまだ使用できない場合、または内部評価中である場合 (たとえば、パフォーマンスへの影響など) は、ドキュメント化しないでください: ドキュメントを追加 (またはマージ) するのは、その機能が安全で、エンドユーザーによる使用とテストの準備が整ってからにしてください。

デフォルトで無効になっている機能フラグについて、エンドユーザーが使用できる場合：

  • デフォルトでは無効になっていると言ってください。
  • GitLab.comで有効になっているかどうかを言ってください。
  • プロジェクトごとに有効か無効かを指定します。
  • 本番での使用が推奨されているかどうかを言ってください。
  • 有効化および無効化の方法を文書化します。

例えば、デフォルトでは無効で、GitLab.com上では無効で、プロジェクト単位で有効/無効にすることができ、本番環境ではまだ使えない機能などです： 

# Feature Name

> - [Introduced](link-to-issue) in GitLab 12.0.
> - It's deployed behind a feature flag, disabled by default.
> - It's disabled on GitLab.com.
> - It's able to be enabled or disabled per-project
> - It's not recommended for production use.
> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#anchor-to-section). **(CORE ONLY)**

(...)

### Enable or disable <Feature Name> **(CORE ONLY)**

<Feature Name> is under development and not ready for production use. It is
deployed behind a feature flag that is **disabled by default**.
[GitLab administrators with access to the GitLab Rails console](../path/to/administration/feature_flags.md)
can enable it for your instance. <Feature Name> can be enabled or disabled per-project

To enable it:

```ruby
# Instance-wide
Feature.enable(:<feature flag>)
# or by project
Feature.enable(:<feature flag>, Project.find(<project id>))
```

To disable it:

```ruby
# Instance-wide
Feature.disable(:<feature flag>)
# or by project
Feature.disable(:<feature flag>, Project.find(<project id>))
```

文書化する機能の状態に応じて、紹介文を調整してください。

デフォルトで有効になった機能

デフォルトで有効になった機能

  • デフォルトで有効になったとします。
  • GitLab.comで有効になっているかどうかを言ってください。
  • プロジェクトごとに有効か無効かを指定します。
  • 本番での使用が推奨されているかどうかを言ってください。
  • 無効にする方法と有効にする方法を説明しています。

例えば、最初はデフォルトで無効な状態でデプロイされた機能が、デフォルトで有効になり、GitLab.comで有効になり、プロジェクトごとに有効/無効にすることができず、本番環境でも使えるようになった場合などです： 

# Feature Name

> - [Introduced](link-to-issue) in GitLab 12.0.
> - It was deployed behind a feature flag, disabled by default.
> - [Became enabled by default](link-to-issue) on GitLab 12.1.
> - It's enabled on GitLab.com.
> - It's not able to be enabled or disabled per-project
> - It's recommended for production use.
> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(CORE ONLY)**

(...)

### Enable or disable <Feature Name> **(CORE ONLY)**

<Feature Name> is under development but ready for production use.
It is deployed behind a feature flag that is **enabled by default**.
[GitLab administrators with access to the GitLab Rails console](..path/to/administration/feature_flags.md)
can opt to disable it for your instance it cannot be enabled or disabled per-project.

To disable it:

```ruby
Feature.disable(:<feature flag>)
```

To enable it:

```ruby
Feature.enable(:<feature flag>)
```

文書化する機能の状態に応じて、紹介文を調整してください。

デフォルトで直接有効になる機能

デフォルトで有効になっている機能

  • デフォルトで有効になっているとします。
  • GitLab.comで有効になっているかどうかを言ってください。
  • プロジェクトごとに有効か無効かを指定します。
  • 本番での使用が推奨されているかどうかを言ってください。
  • 無効にする方法と有効にする方法を説明しています。

例えば、デフォルトで有効になっている機能、GitLab.com で有効になっている機能、プロジェクト単位で有効/無効にできない機能、本番環境ですぐに使える機能などです： 

# Feature Name

> - [Introduced](link-to-issue) in GitLab 12.0.
> - It's deployed behind a feature flag, enabled by default.
> - It's enabled on GitLab.com.
> - It's not able to be enabled or disabled per-project
> - It's recommended for production use.
> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(CORE ONLY)**

(...)

### Enable or disable <Feature Name> **(CORE ONLY)**

<Feature Name> is under development but ready for production use.
It is deployed behind a feature flag that is **enabled by default**.
[GitLab administrators with access to the GitLab Rails console](..path/to/administration/feature_flags.md)
can opt to disable it for your instance.

To disable it:

```ruby
Feature.disable(:<feature flag>)
```

To enable it:

```ruby
Feature.enable(:<feature flag>)
```

文書化する機能の状態に応じて、紹介文を調整してください。

フラッグを外した状態での特徴

機能の準備が整い、フラグが取り除かれたら、ドキュメントをクリーンアップします。 機能のフラグを取り除き、バージョン履歴のノートにフラグに言及したメモだけを残しておきます： 

# Feature Name

> - [Introduced](link-to-issue) in GitLab 12.0.
> - [Feature flag removed](link-to-issue) in GitLab 12.2.

(...)