= 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 ==
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]] ---- === 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. ---- ===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. ---- ===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. ---- ===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. ---- ===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. ---- ===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: 
...
Values:
    OwnedBy UserID()
...
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: 
...
Values:
    DuplicateJobs SetOf(JobID())
...
---- == 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'''
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.
121 History text 72 optional
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.
126 DuplicateOf word 32 optional
DuplicateOf JobID() |- |128 |RelatedJobs |A set of JobIDs for jobs that are similar to the current one, but not exact duplicates.
128 RelatedJobs text 72 optional
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.
129 DuplicateJobs text 72 optional
DuplicateJobs SetOf(JobID()) |- |130 |Fixes |Holds the set of Changelist numbers that are on record as having closed this job.
130 Fixes line 72 optional
Fixes SetOf(Changelist()) |- |132 |Attachments |Identifies the location of any attachments (e.g., core files or Dr. Watson logs) associated with this job.
132 Attachments text 72 optional
Attachments SetOf(FilePath()) |- |133 |DepotAreas |The approximate location in the depot where the underlying bug probably occurs
133 DepotAreas text 72 optional
DepotAreas SetOf(DepotPath()) |}
---- 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]]