ワークアイテム
| Status | Authors | Coach | DRIs | Owning Stage | Created |
|---|---|---|---|---|---|
| accepted | @ntepluhina | @ayufan | @gweaver | ~devops::plan | 2022-09-28 |
このドキュメントは作成中です。いくつかの側面はまだ文書化されていませんが、将来追加する予定です。
概要
ワークアイテムは、Issue、要件、インシデントなど、製品全体でさまざまな種類の構築済みおよび計画済みエンティティをサポートするために作成された新しいアーキテクチャです。同じコア機能を共有しながら、これらのタイプを拡張およびカスタマイズしやすくします。
用語
ワークアイテムアーキテクチャのコンポーネントとプロパティを説明するために以下の用語を使用します。
ワークアイテム
Issue、要件、テストケース、インシデント、タスクの基本タイプ（このリストは将来拡張される予定）。異なるワークアイテムは同じ基本プロパティのセットを持ちますが、ウィジェットのリストは異なります。
ワークアイテムタイプ
ワークアイテムのさまざまなカテゴリのための定義済みタイプのセット。データベースの work_item_types テーブル内で定義されます。
GitLab 製品内のワークアイテムタイプ
上記のデフォルトのワークアイテムタイプは本番データベースに存在しますが、各タイプをレガシー API からワークアイテム API に移行する過程にあるため、GitLab 製品の UI では使用されていない場合があります。レガシーアイテムが存在する場合、すべてのワークアイテムが保存されている issues テーブルにデータを移行し、すべての機能を包括する新しいウィジェットを構築する必要もあります。
| ワークアイテムタイプ | UI の状態 | UI での利用可能性 | issues テーブルへのデータ移行が必要か | ドキュメント |
|---|---|---|---|---|
| タスク | 実装済み | 完全に利用可能 | いいえ | タスク |
| 目標 | 実装済み | フィーチャーフラグの後ろで完全に利用可能 | いいえ | 目標 |
| キーリザルト | 実装済み | フィーチャーフラグの後ろで完全に利用可能 | いいえ | キーリザルト |
| インシデント | 計画中 | - | いいえ | インシデント |
| テストケース | 計画中 | - | いいえ | テストケース |
| 要件 | 計画中 | - | いいえ | 要件 |
| Issue | 開発中 | - | いいえ | Issue |
| エピック | 開発中 | - | はい、進行中 | エピック |
| チケット | 計画中 | - | いいえ | チケット |
ワークアイテムプロパティ
すべてのワークアイテムタイプには以下の共通プロパティがあります:
注意: 詳細については、ワークアイテムのフィールドも参照してください。
id- 一意のワークアイテムグローバル識別子iid- 親ワークスペース（現在ワークスペースはプロジェクトのみ）に対するワークアイテムの内部 ID- ワークアイテムタイプ
- ワークアイテムの変更時刻に関連するプロパティ:
createdAt、updatedAt、closedAt - タイトル文字列
- ワークアイテムの機密状態
- ワークアイテムの状態（オープンまたはクローズ）
- ロックバージョン（ワークアイテムが更新されるたびにインクリメント）
- リソースに対する現在のユーザーの権限
- ワークアイテムウィジェットのリスト
ワークアイテムウィジェット
すべてのワークアイテムタイプは同じ定義済みウィジェットのプールを共有し、特定のタイプでどのウィジェットがアクティブかによってカスタマイズされます。特定のワークアイテムタイプのウィジェットのリストは現在定義済みでカスタマイズできません。ただし、将来的にはユーザーが新しいワークアイテムタイプを作成し、そのウィジェットセットを定義できるようにする予定です。
新しいウィジェットの追加方法を含む、ワークアイテムウィジェットに関する別のページもあります。
ウィジェットタイプ（更新中）
| ウィジェット | 説明 | フィーチャーフラグ | 書き込み権限 | GraphQL サブスクリプションサポート |
|---|---|---|---|---|
| WorkItemWidgetAssignees | ワークアイテムの担当者リスト | エピックワークアイテムタイプの場合 work_items_beta、それ以外は FF なし | Guest | Yes |
| WorkItemWidgetAwardEmoji | ワークアイテムへの絵文字リアクション（アップボート/ダウンボートカウントのサポートを含む） | 誰でも閲覧可能 | No | |
| WorkItemWidgetColor | ワークアイテムの色を設定。注意: 色はエピックでのみ利用可能。 | Reporter | No | |
| WorkItemWidgetCurrentUserTodos | ワークアイテムのユーザー Todo 状態 | 誰でも閲覧可能 | No | |
| WorkItemWidgetDescription | ワークアイテムの説明（編集状態、タイムスタンプ、作成者のサポートを含む） | Reporter | No | |
| WorkItemWidgetDesigns | ワークアイテムのデザイン添付ファイル | Reporter | No | |
| WorkItemWidgetDevelopment | ワークアイテムの関連ブランチとマージリクエストを表示 | Reporter | No | |
| WorkItemWidgetHealthStatus | ワークアイテムのヘルスステータス割り当てサポート | Reporter | No | |
| WorkItemWidgetHierarchy | 子の存在を表すブール値のサポートを含むワークアイテムの階層。 | Guest | No | |
| WorkItemWidgetIteration | ワークアイテムのイテレーション割り当てサポート | Reporter | No | |
| WorkItemWidgetLabels | ワークアイテムに追加されたラベルのリスト（スコープ付きラベルがサポートされているかどうかのチェックを含む） | Reporter | Yes | |
| WorkItemWidgetLinkedItems | relates_to、blocks、blocked_by の関係タイプで、特定のワークアイテムに関連付けられたワークアイテムのリスト。ブロック状態、ブロック対象、ブロック中、関連のカウントのサポートを含む。 | Guest | No | |
| WorkItemWidgetMilestone | ワークアイテムのマイルストーン割り当てサポート | Reporter | No | |
| WorkItemWidgetNotes | ワークアイテム内のディスカッションのリスト | Guest | Yes | |
| WorkItemWidgetNotifications | 現在のユーザーのワークアイテムの通知サブスクリプション状態 | 誰でも閲覧可能 | No | |
| WorkItemWidgetParticipants | ワークアイテムの参加者 | 誰でも閲覧可能 | No | |
| WorkItemWidgetProgress | ワークアイテムの進捗値。注意: 進捗は現在 OKR のみで利用可能。 | okrs_mvc | Reporter | No |
| WorkItemWidgetRequirementLegacy | レガシー要件 | No | ||
| WorkItemWidgetRolledupDates | エピックワークアイテムの開始日と期限を設定し、子ワークアイテムから開始日と期限をロールアップする | Reporter | No | |
| WorkItemWidgetStartAndDueDate | ワークアイテムの開始日と期限を設定 | Reporter | No | |
| WorkItemWidgetStatus | タイプが要件の場合のワークアイテムのステータス（unverified、satisfied、failed のステータスタイプが可能） | No | ||
| WorkItemWidgetTestReports | ワークアイテムに関連するテストレポート | |||
| WorkItemWidgetTimeTracking | ワークアイテムに費やした合計時間を追跡 | Reporter | No | |
| WorkItemWidgetWeight | ワークアイテムのウェイトを設定 | Reporter | No | |
| WorkItemWidgetLock | ワークアイテムのロック/ロック解除 | Reporter | No |
ウィジェットの可用性（更新中）
| ウィジェット | エピック | Issue | タスク | 目標 | キーリザルト |
|---|---|---|---|---|---|
| WorkItemWidgetAssignees | ✅ | ✔️ | ✅ | ✅ | ✅ |
| WorkItemWidgetAwardEmoji | ✅ | ✔️ | ✅ | ✅ | ✅ |
| WorkItemWidgetColor | ✅ | ❌ | ❌ | ❌ | ❌ |
| WorkItemWidgetCurrentUserTodos | ✅ | ✅ | ✅ | ✅ | ✅ |
| WorkItemWidgetDescription | ✅ | ✅ | ✅ | ✅ | ✅ |
| WorkItemWidgetDesigns | ✔️ | ✅ | ❌ | ❌ | ❌ |
| WorkItemWidgetDevelopment | ❌ | ✅ | ❌ | ❌ | ❌ |
| WorkItemWidgetHealthStatus | ✅ | ✅ | ✅ | ✅ | ✅ |
| WorkItemWidgetHierarchy | ✅ | ✅ | ❌ | ✅ | ❌ |
| WorkItemWidgetIteration | ❌ | ✅ | ✅ | ❌ | ❌ |
| WorkItemWidgetLabels | ✅ | ✅ | ✅ | ✅ | ✅ |
| WorkItemWidgetLinkedItems | ✅ | ✅ | ✅ | ✅ | ✅ |
| WorkItemWidgetMilestone | ❌ | ✅ | ✅ | ✅ | ❌ |
| WorkItemWidgetNotes | ✅ | ✅ | ✅ | ✅ | ✅ |
| WorkItemWidgetNotifications | ✅ | ✅ | ✅ | ✅ | ✅ |
| WorkItemWidgetParticipants | ✅ | ✅ | ✅ | ✅ | ✅ |
| WorkItemWidgetProgress | ❌ | ❌ | ❌ | ✅ | ✅ |
| WorkItemWidgetRequirementLegacy | ❌ | ❌ | ❌ | ❌ | ❌ |
| WorkItemWidgetRolledupDates | ✅ | ❌ | ❌ | ❌ | ❌ |
| WorkItemWidgetStartAndDueDate | ❌ | ✅ | ✅ | ❌ | ✅ |
| WorkItemWidgetStatus | ❓ | ❓ | ❓ | ❓ | ❓ |
| WorkItemWidgetTestReports | ❌ | ❌ | ❌ | ❌ | ❌ |
| WorkItemWidgetTimeTracking | ✅ | ✅ | ✅ | ❌ | ❌ |
| WorkItemWidgetWeight | ❌ | ✅ | ✅ | ❌ | ❌ |
凡例
- ✅ - ウィジェット利用可能
- ✔️ - ウィジェット利用可能予定
- ❌ - ウィジェット利用不可
- ❓ - ウィジェット検討中
- 🔍 - 代替ウィジェット計画中
ワークアイテムの関係
ワークアイテムはさまざまな方法で他のワークアイテムに関連付けることができます:
- 親: 現在のワークアイテムに対する直接の先祖であり、その完了は現在のワークアイテムの完了に依存します。
- 子: 現在のワークアイテムの直接の子孫であり、このワークアイテムの完了に貢献します。
- ブロック対象: 現在のワークアイテムの完了を妨げるワークアイテム。
- ブロック中: 現在のワークアイテムによって完了がブロックされるワークアイテム。
- 関連: 現在のワークアイテムの主題に関連するワークアイテムですが、直接このワークアイテムの完了に貢献またはブロックするものではありません。
階層
親子関係はワークアイテムの階層の基盤を形成します。各ワークアイテムタイプには、そのタイプの親または子になれるタイプの定義済みセットがあります。
タイプが拡張し、親アイテムが自分自身の親アイテムを持つようになると、階層機能は指数関数的に成長できます。
現在、以下の親子関係が許可されています:
| タイプ | 親になれる対象 | 子になれる対象 |
|---|---|---|
| エピック | エピック | エピック |
| Issue | タスク | エピック |
| タスク | なし | Issue |
| 目標 | 目標 | 目標 |
| キーリザルト | なし | 目標 |
ワークアイテムビュー
グローバルワークアイテム id を識別子として使用して、あらゆるタイプのワークアイテムをレンダリングする新しいフロントエンドビュー。
タスク
タスクは特別なワークアイテムタイプです。タスクは Issue に子アイテムとして追加でき、Issue ビューのモーダルに表示できます。
フィーチャーフラグ
これは多数の可動部分を含む大きなプロジェクトであるため、利用可能なウィジェットのプロモーションを追跡するためにフィーチャーフラグが使用されています。以下の表は使用されているさまざまなフィーチャーフラグとそれらが利用可能なオーディエンスを示しています。
| フィーチャーフラグ名 | オーディエンス |
|---|---|
work_items | デフォルトでオン |
work_items_beta | gitlab-org、gitlab-com |
work_items_alpha | gitlab-org/plan-stage |
コンテキストビューのフィーチャーフラグ
| フィーチャーフラグ名 | 制御エリア | 状態 |
|---|---|---|
work_items_alpha | コンテキストビュー内の子アイテム | gitlab-org/plan-stage で有効 |
epics_list_drawer | エピックリスト、エピックボード | gitlab-org/plan-stage で有効 |
issues_list_drawer | Issue リスト、Issue ボード | 無効 |
Issue ワークアイテムビューのフィーチャーフラグ
| フィーチャーフラグ名 | 制御エリア | 状態 |
|---|---|---|
work_item_view_for_issues | Issue のワークアイテムビューを有効にする | デフォルトでオン |
work_items_view_preference | ヘッダーセクションで Issue ワークアイテムビューの有効/無効を切り替えるトグルを表示 | デフォルトでオン |
エピックワークアイテム固有のフィーチャーフラグについては、エピックワークアイテム移行エピックを参照してください。
動機
ワークアイテムの主な目標は、あらゆる業界の知識労働者にとって最も人気の高いコラボレーションツールとなるための計画ツールセットを強化することです。
- Issue、インシデント、エピック、テストケースなどの類似アイテムを標準プラットフォームに集約して、メンテナンスを簡素化し、エクスペリエンスの一貫性を高める
- GitLab 固有のニュアンスを学ばずにユーザーが計画できるように、共通の計画概念のファーストクラスサポートを可能にして複雑さを軽減する
目標
スケーラビリティ
現在、Issue、エピック、マージリクエストなどのさまざまなエンティティは多くの類似機能を共有していますが、これらの機能はエンティティタイプごとに個別に実装されています。これにより、新機能の実装や既存機能のリファクタリングが困難になります。例えば、Issue とインシデントに新機能を追加する計画がある場合、Issue タイプとインシデントタイプで個別に実装する必要があります。ワークアイテムでは、新機能はすべての既存タイプのウィジェットとして実装されるため、アーキテクチャがよりスケーラブルになります。
柔軟性
既存の実装では、issuable、マージリクエスト、エピックなどに対して厳格な構造があります。この構造はバックエンドとフロントエンドの両方で定義されているため、変更には協調的な取り組みが必要です。また、フラグのセットを導入してあらゆる既存機能を有効/無効にすることなく、この構造をユーザーがカスタマイズ可能にすることも非常に困難です。ワークアイテムアーキテクチャにより、フロントエンドはワークアイテムウィジェットを柔軟にレンダリングできます: ワークアイテムウィジェットに存在するものはすべてページにレンダリングされます。これにより、変更を迅速に行え、構造がより柔軟になります。例えば、インシデントページでラベルの表示を停止したい場合、バックエンドのインシデントワークアイテムタイプからラベルウィジェットを削除します。また、将来的にはユーザーがカスタムワークアイテムタイプで表示するウィジェットのセットを定義できるようになります。
一貫したエクスペリエンス
異なるエンティティで類似機能の一貫した動作を実現しようとしても、実装に違いが生じています。例えば、GraphQL API を通じてマージリクエストのラベルを更新するには専用の setMergeRequestLabels ミューテーションを使用しますが、Issue の場合はより粗粒度な updateIssue を呼び出します。これにより、フロントエンドと外部 API ユーザーの両方に一貫性のないエクスペリエンスが生じます。結果として、エピック、Issue、要件など、すべてが類似しているが共通のインタラクションに微妙な違いがあり、ユーザーはそれぞれの動作の複雑なメンタルモデルを持つ必要があります。
ワークアイテムアーキテクチャは、すべてのタイプのすべての機能を一貫して、ワークアイテムウィジェットとして実装することを目的として設計されています。
解決すべき高レベルのアーキテクチャ問題
- エピックをワークアイテムタイプに移行するためにグループとプロジェクトの統合をどのようにバイパスできるか
- 特定のワークアイテムタイプの親子関係を扱う: エピック > Issue > タスク、および同じワークアイテムタイプへ: Issue > Issue
- カスタムワークアイテムタイプとカスタムウィジェットの実装
