Perforceのカスタマイズ: ジョブ仕様

Perforceのジョブでは、チェンジリストを機能拡張要求、問題報告、その他のユーザ定義のタスクにリンクさせることができます。また、Perforceはサードパーティの欠陥追跡ツールとPerforceとを統合する手段として、P4DTG(Perforce Defect Tracking Gateway)も提供します。詳細については、サードパーティの欠損追跡システムと連携するを参照してください。

Perforceユーザによるp4 jobの使用方法については、『P4ユーザーズガイド』を参照してください。この章では、管理者によるジョブシステムの変更について説明します。

Perforceのデフォルトのジョブテンプレートには、ジョブ追跡用のフィールドが5つあります。Perforceでプロジェクトの規模が小さいうちは、これらのフィールドだけで十分ですが、プロジェクトの規模が大きくなってくると、これらのフィールドの情報だけでプロジェクトを管理しきれなくなる場合があります。ジョブテンプレートの内容は、p4 jobspecコマンドを使用して変更することができます。p4 jobspecは、Perforce管理者のみが使用できるコマンドです。

この章では、Perforceジョブテンプレート変更のしくみを説明します。

Warning

Perforceジョブテンプレートへの不適切な変更は、サーバデータベース破損の原因になる恐れがあります。本章の最後に記載されたジョブテンプレートへの変更に関する警告、注意、勧告を参照してください。

Perforceのデフォルトのジョブテンプレート

Perforceのジョブがどのように指定されるかを理解するために、Perforceのデフォルトのジョブテンプレートについて見てみましょう。この章で示されている例は、このテンプレートに適宜修正を加えて作成されています。

PERFORCEのデフォルトのジョブテンプレートを使用すると、以下の形式でジョブが作成されます。 

# A Perforce Job Specification.
#
#  Job:         The job name.  'new' generates a sequenced job number.
#  Status:      Either 'open', 'closed', or 'suspended'. Can be changed.
#  User:        The user who created the job. Can be changed.
#  Date:        The date this specification was last modified.
#  Description: Comments about the job.  Required.
Job:    new
Status: open
User:   edk
Date:   2011/06/03 23:16:43
Description:
        <enter description here>

このジョブの生成に使用したテンプレートは、p4 jobspecにより表示して編集することができます。デフォルトのジョブ仕様テンプレートは、次のように表示されます。 

# A Perforce Job Specification.
#
#  Updating this form can be dangerous!
#  See 'p4 help jobspec' for proper directions.
Fields:
      101 Job word 32 required
      102 Status select 10 required
      103 User word 32 required
      104 Date date 20 always
      105 Description text 0 required
Values:
      Status open/suspended/closed
Presets:
      Status open
      User $user
      Date $now
      Description $blank
Comments:
      # A Perforce Job Specification.
      #
      # Job: The job name. 'new' generates a sequenced job number.
      # Status: Either 'open', 'closed', or 'suspended'. Can be changed.
      # User: The user who created the job. Can be changed.
      # Date: The date this specification was last modified.
      # Description: Comments about the job. Required.

ジョブテンプレートのフィールド

p4 jobspecの形式には4つのフィールドがあります。これらのフィールドは、サーバに保存されたすべてのPerforceジョブのテンプレートを定義しています。以下の表に、フィールドおよびフィールドタイプを示します。

フィールド/フィールドタイプ

意味

Fields:

各ジョブに含めるフィールドのリストです。

各フィールドはID番号、名前、データタイプ、長さ、および設定で構成されます。

フィールド名にスペースを含めることはできません。

Values:

データタイプがselectのフィールドのリストです。

各selectデータタイプのフィールドには、フィールド名、スペース、およびスラッシュで区切った有効な値のリストからなる1行を追加しなければなりません。

Presets:

各フィールドと、そのデフォルト値のリストです。

デフォルト値は、Perforceでサポートされているリテラル文字列または変数のいずれかです。

Comments:

p4 jobフォームの先頭に表示されるコメントです。このコメントは、P4V(Perforce Visual Client)でツールチップの表示にも使用されます。

Fields: フィールド

Fields:のp4 jobspecフィールドは、ジョブで追跡するフィールドをリスト表示し、またp4 jobのフォーム上での表示順位を指定します。

デフォルトのFields:フィールドには、以下のフィールドが含まれます。 

Fields:
      101 Job word 32 required
      102 Status select 10 required
      103 User word 32 required
      104 Date date 20 always
      105 Description text 0 required

Warning

101～105のフィールドを、変更、リネーム、再定義しないでください。フィールド101～105はPerforceが使用するため、削除も変更もしてはいけません。p4 jobspecは、ジョブに新しいフィールド(106以降)を追加する目的のみに使用してください。

各フィールドは別々の行にリストされていなければなりません。フィールドは、以下の5つのフィールド記述子の1行で定義します。

フィールド記述子

意味

ID番号

このフィールドのインデックスとなる固有の整数識別子です。フィールドが生成されジョブがシステムに入力された後も、フィールド名は変更可能です。ただし、ID番号を変更すると、そのフィールドのデータにアクセスすることはできなくなります。

指定できるID番号の範囲は、106～199です。

名前

p4 jobフォームに表示されるフィールド名です。スペースを含めることはできません。

データタイプ

次の表に記述した5つのデータタイプ(word、text、line、select、date、bulk)のうちいずれかです。

長さ

P4V(Perforce Visual Client)に表示されるフィールドのテキストボックスの推奨サイズです。複数行入力できるテキストボックスを表示する場合は、長さを0と指定します。1行のテキストボックスにする場合は、最大入力文字数のLengthを入力します。

このフィールドの値はPerforceのコマンドラインから編集するジョブには影響せず、サーバに保存された実際の値の長さとも関係ありません。

フィールドタイプ

フィールドが読み取り専用かどうか、デフォルト値が使用されているか、必須であるかなどを指定します。このフィールドでは以下の値が有効です。

  • optional: 任意の値を指定することができます。削除も可能です。

  • default: デフォルト値が与えられます。変更または消去が可能です。

  • required: デフォルト値が与えられます。変更はできますが、空白にしておくことはできません。

  • once: 読み取り専用です。最初にデフォルト値に設定され、以後変更はできません。

  • always: 読み取り専用です。ジョブを保存するたびに、値がデフォルト値にリセットされます。変数$nowでジョブ更新日を変更するとき、変数$userでジョブを最後に更新したユーザの名前を変更するときにのみ有用です。

各フィールドには以下の6つのデータタイプが存在します。

フィールドタイプ

説明

例

word

スペースを持たない1つの単語です。

ユーザID: edk

text

1行または複数行のテキストブロックです。

ジョブの記述。

line

1行のテキストです。

ユーザの実名: Ed K.

select

1組の値セットのうち1つ。

データタイプがselectの各フィールドは、ジョブ仕様に入力されたValues:フィールドに対応する行が指定されていなければなりません。

ジョブの状態。次のいずれか: open/suspended/closed

date

日付です。

ジョブ作成の日付と時刻: 1998/07/15:13:21:46

bulk

複数行に展開可能なテキストブロック。ただし、p4 jobs -eによる検索用のインデックスは付けられていません。

テキスト検索の対象とならない英数字データ。

Values: フィールド

フィールドのデータタイプがselectのすべてのフィールドで、Values:フィールドに行を入力し選択肢を指定します。各行にはフィールドの名前と、スペース1個に続けて、選択肢をスラッシュ区切りで記述します。

Perforceのデフォルトのジョブ仕様では、Status:フィールドのデータタイプだけがselectになっていて、その選択肢は以下のように設定されています。 

Values:
      Status open/suspended/closed

Presets: フィールド

フィールドタイプがoptional以外のフィールドは、すべてデフォルト値を必要とします。フィールドにデフォルト値を割り当てるには、ジョブ仕様のPresetsの下にフィールド名とそのデフォルト値を1行で記述します。デフォルト値には1行からなるあらゆる文字列を使用できます。

デフォルト値として、以下の3つの変数を使用することができます。

変数

値

$user

ジョブを作成するPerforceユーザです。P4USERの環境変数で指定するか、p4 -u username jobでオーバーライドして指定します。

$now

ジョブを保存するときの日付と時刻です。

$blank

テキスト<enter description here>です。

ユーザによるジョブ入力時、ジョブ仕様でプリセット値が$blankに設定されているフィールドがある場合、ジョブをシステムに追加する前に、そのフィールドに必要な記述を入力しておかなければなりません。

標準的なジョブテンプレートのPresets: フィールドは、以下のようになります。 

Presets:
      Status open
      User $user
      Date $now
      Description $blank

Presets: フィールドを使用してデフォルトの修正ステータスを変更する

ジョブステータスフィールド(フィールド102)のPresets:エントリには、p4 fix、p4 change -s、p4 submit -sにデフォルトの修正ステータスを供給するための特殊な構文があります。

デフォルトの修正ステータスをclosedからその他のfixStatus(好みのfixStatusが既に有効なselectの設定値としてValues:フィールドに定義されていると仮定し)に変更するには、次の構文を使用します。 

Presets:
      Status openStatus,fix/fixStatus

p4 fix、p4 change、p4 submitのデフォルトの動作を変更して、ジョブの修正後またはチェンジリストのサブミット後にジョブステータスが変わらないようにするには、特殊なfixStatusであるsameを使用します。例: 

Presets:
      Status open,fix/same

Comments: フィールド

Comments:フィールドは、p4 jobフォームの先頭に表示されるコメントを記述します。p4 jobは、selectのフィールドで有効な値や、どのフィールドに記述が必要かなどの情報をユーザに通知しません。したがって、各フィールドについてユーザが必要とするすべての情報をコメントとして記述する必要があります。

Comments:フィールドの各行は左端から少なくとも1タブはインデントさせてコメント文字の#で始めます。

p4 jobのデフォルトのジョブテンプレートのComment: フィールドは以下のように表示されます。 

Comments:
      # A Perforce Job Specification.
      # Job: The job name. 'new' generates a sequenced job number.
      # Status: Either 'open', 'closed', or 'suspended'. Can be changed
      # User: The user who created the job. Can be changed.
      # Date: The date this specification was last modified.
      # Description: Comments about the job. Required.

このフィールドは、P4V(Perforce Visual Client)でツールチップの表示にも使用されます。

警告、注意、勧告

このセクションの内容は、すでに本章のほかの箇所でもお伝えしていますが、重要なことなので、繰り返しお伝えしておきます。p4 jobspecでジョブ仕様を編集するときは、ここに示す指針に従ってください。

Warning

ジョブ仕様の編集を開始する前に、必ずこのセクションの内容を読んで理解してください。

  • 101～105のフィールドを、変更、リネーム、再定義しないでください。これらのフィールドはPerforceが使用するため、削除も変更もしてはいけません。p4 jobspecは、ジョブに新しいフィールド(106以降)を追加する目的のみに使用してください。

    フィールド101はPerforceに必要です。リネームすることも削除することもできません。

    フィールド102～105は、Perforceのアプリケーション専用です。これらのフィールドをリネームまたは削除することは可能ですが、望ましくありません。Perforceアプリケーションは、チェンジリストがサブミットされるたびにフィールド102(Status:フィールド)の値をclosed(またはフィールド102のPresets:に定義されたその他の値)に設定することがあります。これは、管理者がフィールド102を、closedを許容値として含まないフィールドとして使用するように再定義しても変わりません。のような再定義は予測不可能な混乱を生じる危険性があります。

  • フィールドが作成され、ジョブが入力された後は、そのフィールドのID番号を変更しないでください。p4 jobでそのフィールドに入力したすべてのデータにアクセスできなくなります。

  • フィールド名はいつでも変更可能です。フィールド名を変更するときは、p4 jobspecの他のフィールドに参照として記述されたフィールド名も忘れずに変更してください。例えば、severityと名付けたフィールド106を作成した後、フィールド名をbug-severityに変更する場合は、ジョブ仕様のPresets:フィールドの対応する行に記述された同じフィールド名も、bug-severityに変更します。

  • Comments:フィールドに記述するコメントは、ユーザに各フィールドの要件を知らせる唯一の手段です。これらのコメントはわかりやすく、完全なものにしてください。このコメントは、P4V(Perforce Visual Client)でツールチップの表示にも利用されます。

例: カスタムテンプレート

より複雑なジョブ仕様と、その仕様に基づき表示されるジョブフォームの例を以下に示します。 

# A Custom Job Specification.
#
#  Updating this form can be dangerous!
#  See 'p4 help jobspec' for proper directions.
Fields:
        101 Job word 32 required
        102 Status select 10 required
        103 User word 32 required
        104 Date date 20 always
        111 Type select 10 required
        112 Priority select 10 required
        113 Subsystem select 10 required
        114 Owned_by word 32 required
        105 Description text 0 required
Values:
        Status open/closed/suspended
        Type bug/sir/problem/unknown
        Priority A/B/C/unknown
        Subsystem server/gui/doc/mac/misc/unknown
Presets:
        Status open
        User setme
        Date $now
        Type setme
        Priority unknown
        Subsystem setme
        Owned_by $user
        Description $blank
Comments:
        # Custom Job fields:
        # Job:    The job name. 'new' generates a sequenced job number.
        # Status: Either 'open', 'closed', or 'suspended'. Can be changed
        # User:   The user who created the job. Can be changed.
        # Date:   The date this specification was last modified.
        # Type:          The type of the job. Acceptable values are
        #                'bug', 'sir', 'problem' or 'unknown'
        # Priority:      How soon should this job be fixed?
        #                Values are 'a', 'b', 'c', or 'unknown'
        # Subsystem:     One of server/gui/doc/mac/misc/unknown
        # Owned_by:      Who's fixing the bug
        # Description: Comments about the job. Required.

ジョブフォームで表示されるフィールドの順番は、p4 jobspecフォームのFields:のフィールド記述順によって決まります。フィールドはID番号順に並んでいる必要はありません。

この例のカスタムジョブ仕様に対してp4 jobを実行すると、以下のようなジョブフォームが表示されます。 

# Custom Job fields:
# Job:    The job name. 'new' generates a sequenced job number.
# Status: Either 'open', 'closed', or 'suspended'. Can be changed
# User:   The user who created the job. Can be changed.
# Date:   The date this specification was last modified.
# Type:          The type of the job. Acceptable values are
#                'bug', 'sir', 'problem' or 'unknown'
# Priority:      How soon should this job be fixed?
#                Values are 'a', 'b', 'c', or 'unknown'
# Subsystem:     One of server/gui/doc/mac/misc/unknown
# Owned_by:      Who's fixing the bug
# Description: Comments about the job. Required.
Job:    new
Status: open
User:   setme
Type:   setme
Priority:       unknown
Subsystem:      setme
Owned_by:       edk
Description:
        <enter description here>

サードパーティの欠損追跡システムと連携する

Perforceは現在、Perforceとサードパーティの欠陥追跡システムとを統合するために、2種類の独立したプラットフォームを提供しています。どちらのプラットフォームでも、Perforceのジョブシステムと外部の欠陥追跡システムとの間で情報を共有することができます。

P4DTG(Perforce Defect Tracking Gateway)

P4DTG(Perforce Defect Tracking Gateway)は、グラフィカルな構成エディタと複製エンジンの両方を含む統合プラットフォームです。

P4DTGにはグラフィカルな構成エディタが含まれており、これを使用してPerforceジョブと外部システムとの関係を制御することができます。2つのシステム間でのデータの伝達は、複製エンジンにより調整されます。P4DTGにはHP Quality Center、JIRA、Redmine、Bugzillaのプラグインが同梱されています。

詳細情報は、下記の製品ページを参照してください。

http://www.perforce.com/product/components/defect_tracking_gateway

このページからはP4DTGの機能概要やP4DTG自体のダウンロードのほか、Perforceサーバと欠陥追跡ツールとの間でデータを複製するためにゲートウェイをインストールし構成する方法が解説された『Perforce Defect Tracking Gateway Guide』へのリンクが提供されています。

独自の連携システムを構築する

最初はPerforceの統合ツールを使用しない場合でも、PerforceジョブシステムをPerforceと欠陥追跡システムとのインターフェイスとして利用することができます。アプリケーションに応じて、セットアップするインターフェイスは以下の1つまたは複数で構成されます。

  • 欠陥追跡システム内でバグが追加、更新、削除されるたびにPerforceのジョブを追加、更新、削除する欠陥追跡システム側のトリガまたはスクリプト。

    サードパーティのシステムはデータを生成し、それをp4 jobの手動(対話形式の)起動用フォームに合わせて再フォーマットするスクリプトに渡します。スクリプトはそこで生成されたフォームをp4 job -iコマンドの標準入力として送出します。

    p4 jobに標準入力から直接ジョブフォームを読み込ませる場合は、p4 jobの-iフラグを使用します。通常ユーザが行う対話形式の「フォームアンドエディタ」方式の操作は使用しません。-iオプションを用いたPerforceの自動化についての詳細は、『Perforce コマンドリファレンス』を参照してください。

  • 必要なバグ修正完了情報を収集するために、サブミットされたチェンジリストをチェックするPerforce側のトリガ。

  • ジョブ修正完了のチェンジリストが無事にサブミットされたことをチェックし、適切なコマンドを発行して欠陥追跡システムの該当データを更新するPerforceレビューdaemon。

トリガーおよびレビューdaemonについての詳細や使用例は、“Perforceのスクリプト: トリガとデーモン”を参照してください。