= Enhanced Jobs Project (EJP) =
== Background and Overview ==
The Enhanced Jobs Project (EJP) was developed in response to growing
concerns about the limitations of the jobs subsystem, as compared to
some of the commercial defect tracking systems available today.
EJP does not attempt to transform the current jobs system into a
fully-functioned defect tracking application. What it does is address
what have been identified as the key "pain points" in the
current system, while correcting a couple of long-standing weaknesses.
EJP is a set of small improvements to the standard jobs system that
were designed to make our life with jobs just a little easier.
----
== Features of the Enhanced Jobs Project ==
<blockquote>
EJP provides the following features:
* [[#Improved_triggers_on_jobs|Improved triggers on jobs]]
* [[#Improved_support_for_handling_of_duplicates|Improved support for handling of duplicates]]
* [[#Improved_support_for_handling_of_related_jobs|Improved support for handling of related jobs]]
* [[#Job_change_history|Job change history]]
* [[#Better_management_of_job_ownership|Better management of job ownership]]
* [[#New_validations_on_jobspec_fields|New validations on jobspec fields]]
----
<span id="Improved_triggers_on_jobs"></span>
=== Improved triggers on jobs ===
As part of this project, a couple of holes in the server's trigger
handling were repaired:
* Any event that affects a job will fire a form-commit trigger. For example:
** p4 submit
** p4 fix
** p4 fix -d
** p4 changelist
* The JobID of a newly-submitted job will now be available to "commit" triggers.
----
<span id="Improved_support_for_handling_of_duplicates"></span>
===Improved support for handling of duplicates===
The proper handling of duplicates involves several separate
steps, and has always been prone to error. This project automates
some of that process, and imposes restrictions to prevent some
common errors. In a nutshell, this feature:
* Makes sure that when a bug is marked as a "duplicate" the job that it is a duplicate of is identified.
* Automatically updates the corresponding job to identify the duplicate one as being related to it. (I.e., creates the cross-reference.)
* Copies customer and call information from the duplicate job back to the original, or primary one.
What this means for users is that all we'll have to do, when we
discover a duplicate, is enter the primary, or original job number
in the DuplicateOf field and set the Status to "duplicate",
and EJP will take care of the rest.
----
<span id="Improved_support_for_handling_of_related_jobs"></span>
===Improved support for handling of related jobs===
Currently, it's common for a job description to include
a notation like, "See also job012345". EJP formalizes this practice
by adding a RelatedJobs field that will hold a set of JobIDs for
jobs that are similar to the current one, but that might not be
exact duplicates. When a JobID is entered in this field, a
corresponding entry is automatically made in the related job,
providing more complete cross-referencing of this data.
Note that this behavior is similar to the "duplicate"
handling described above. The main difference is that customer and
call information is not affected for "related" jobs.
----
<span id="Job_change_history"></span>
===Job change history===
Currently, anyone can view the history of a job by looking
at its revision history in the spec depot. This is very convenient
for a single job, but can be labor intensive if a large number of
jobs need to be reviewed.
The Enhanced Jobs Project addresses this problem by adding
a system-maintained field (121 History) that holds a brief
summary of each change that affects a job. With this feature, you
can get a quick overview of the history of a job by looking at a
single field.
----
<span id="Better_management_of_job_ownership"></span>
===Better management of job ownership===
One of the key "pain points" identified in the current
jobs system is that job ownership is mainly an ad hoc and/or manual
process. Because of this, it's fairly easy for a job to languish
without an owner, which can seriously delay any action being taken
on it.
EJP implements an internal data structure that is used to
automatically assign an owner to a job, based on the job's
Subsystem and Status. The standard assignments can be overridden,
if necessary, but if a subsystem has been configured to have a
default set of owners (based on job status), then the owner field
can't inadvertently be left blank. That is, if the user entering
the job doesn't specify an owner, then the system will fill that
field in with the designated default owner.
With EJP, if the Status field is updated, but the OwnedBy field
is not, ownership will automatically transfer to the appropriate
individual (based on a pre-defined matrix of subsystems, status
values, and usernames). If the OwnedBy field is explicitly set,
EJP will not update it using that matrix, but will retain the
value that was entered.
----
<span id="New_validations_on_jobspec_fields"></span>
===New validations on jobspec fields===
EJP provides the following validation specifiers, which can be
used for jobspec fields:
* '''JobID()''' - Value must be an existing JobID.
* '''UserID()''' - Must be an existing UserID.
* '''Changelist()''' - Must be an existing Changelist number
* '''DepotPath()''' - Must be a path to a file or directory in the depot.
* '''FilePath()''' - Must be a path to a specific file in the depot.
Field validation specifiers are set in the "Values"
section of the jobspec. For example:
<pre>
...
Values:
OwnedBy UserID()
...
</pre>
In addition, two kinds of "group" fields have been
defined:
* '''ListOf()''' - An ordered list of a specified type.
* '''SetOf()''' - A collection of unique values of a specified type.
Lists and collections are also specified in the Values section
of the jobspec. For example:
<pre>
...
Values:
DuplicateJobs SetOf(JobID())
...
</pre>
----
== Administration ==
On a day-to-day basis, EJP will "just work", but when
product assignments or procedures change, EJP will need to be
adjusted accordingly. This will involve making updates to one of
the following files:
* P4Data.rb
* P4Logic.rb
* job_commit.rb
----
'''P4Data.rb'''
P4Data.rb encapsulates:
* The default ownership for a job, based on subsystem and status.
* The name of the field that will be used to maintain the job's change history.
* A list of fields that will not be included in the change history summary.
* A list of the fields that are maintained by EJP, and that are to be treated as "read only" otherwise.
* The names of fields that will be copied during duplicate processing.
----
'''P4Logic.rb'''
P4Logic.rb holds the logic for handling new jobs and changed
jobs, including duplicates, and "related" jobs:
* Blocks manual entry into system-maintained fields.
* Copies data from duplicate jobs to the original, or primary, one.
* Updates the History field.
----
'''job_commit.rb'''
* Rejects the job change if any value was entered into a system-maintainted field.
* If the job status is changed to "Duplicate", moves customer call information (call numbers and contacts) from the duplicate job to the original, or primary, one.
* Updates the History field to add a summary of the current change.
----
'''New Fields for the production jobspec'''
<blockquote>
To support all of the new features in the Enhanced Jobs Prototype,
several fields will need to be added to the production jobspec:
{| border="1"
|-
!Field #
!Field Name
!Description/Field Definition/Values Clause
|-
|121
|History
|A list of 1-line change summaries for this job.<br>
121 History text 72 optional<br>
History ListOf(line)
|-
|126
|DuplicateOf
|Holds the JobID of the job of which the current one is a duplicate. There can only be one of these, since there can only be one "original", or "primary" job.<br>
126 DuplicateOf word 32 optional<br>
DuplicateOf JobID()
|-
|128
|RelatedJobs
|A set of JobIDs for jobs that are similar to the current one, but not exact duplicates.<br>
128 RelatedJobs text 72 optional<br>
RelatedJobs SetOf(JobID())
|-
|129
|DuplicateJobs
|This field is the inverse of DuplicateOf, and holds a set of JobIDs for jobs that have been marked as duplicates of the current job.<br>
129 DuplicateJobs text 72 optional<br>
DuplicateJobs SetOf(JobID())
|-
|130
|Fixes
|Holds the set of Changelist numbers that are on record as having closed this job.<br>
130 Fixes line 72 optional<br>
Fixes SetOf(Changelist())
|-
|132
|Attachments
|Identifies the location of any attachments (e.g., core files or Dr. Watson logs) associated with this job.<br>
132 Attachments text 72 optional<br>
Attachments SetOf(FilePath())
|-
|133
|DepotAreas
|The approximate location in the depot where the underlying bug probably occurs<br>
133 DepotAreas text 72 optional<br>
DepotAreas SetOf(DepotPath())
|} </blockquote>
----
Again, once the system is up and running, administration requirements
are expected to be minimal, and to consist primarily of making changes
to P4Data.rb to keep the mappings between subsystems and owners up to
date.
----
[[Category:Perforce]]
[[Category:Jobs]]