![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Standard Task Kinds This chapter discusses the standard task kinds which are included with Rational Summit/TM. They are located within the following view:
$APEX_BASE/task/task_kinds.ss/all.rel
If you want to customize any of these task kinds, first use the Tasks > Copy Kind Directory menu item or the copy_task_kind command to create a local copy of the task kind directory in some other view (either within this same subsystem or in one of your own choosing).
Example Task Kinds - Defect and FeatureDefect and feature are relatively simple task kinds which serve to illustrate the general capabilities of Rational Summit/TM. They are intended to be used as introductory examples for learning how to use the system. As such, they lack many of the rich details that a "full service" task kind has to offer. However, they include the basic features found in most task kinds and make good learning tools.
Change Management Task KindsThe change management task kinds are provided as a starting point from which you can design your own task kinds to help you manage changes to Summit/CM controlled source files for a software development project. Only a limited amount of customizing is needed to make these task kinds ready to use. These task kinds are intended to be used primarily to help the members of a development team keep track of the programming and documenting tasks that they are expected to perform for the products they support. They do not include many of the formal controls, metrics, and interdepartmental policy and procedural features that a full fledged "software process" would be expected to provide. Rather, they support a more informal "light weight" software development team tool that is useful for monitoring, preserving and directing the state and status of multiple programming assignments. As such, the degree of control and overhead is reduced and greater customization and flexibility is encouraged. The task kinds are meant to be as unintrusive as possible while still providing a useful record of development activities.
There are actually three change management task kinds: the master change task kind, the document change task kind, and the software change task kind. From each task kind, of course, multiple tasks of the given task kind can be created. A master change task represents the overall goal to fix a particular bug or add some feature to a product. It provides a central point of access and control over one or more documentation and software change tasks. A documentation change task is used to track any necessary documentation changes which may involve several documents and multiple revisions. A software change task tracks changes to the software and is the task to which source versions are usually associated. Each software change task tracks one set of source changes as it takes them through a single development cycle of code, test and (pre)integrate.
The change management task kinds depend on the following task roles with the associated (typical) responsibilities:
The assignment of task roles to actual people is not dictated by the change management task kinds. All (or most of) the roles could be filled by the same person, they could be distributed among the personnel of a single department, or they could be assigned to different departments.
The actual change management task kinds delivered with Rational Summit/TM are generic versions. They include a number of enumerated task fields whose values must first be defined since they are customer and product dependent. Note that when "instantiating" the generic versions, new names should be chosen for both the new task kinds and their associated task editors.
Change Task Kind
The generic change task kind is called change.
Policy Switches
The change task kind defines the following prefix and suffix for its part of the task id generation policy:
Prefix: C Suffix:
This, of course, can be changed to whatever is desired.
Task Fields
The change task kind supports the following fields. The meaning of each field is described after its name and associated field type. Note that, except where otherwise indicated, the name of a field in the change task editor is identical to its formal name in the task kind Fields file. The fields are split up into four groups: common information, development information, problem report information and task history information.
Common Information Group
The common information group contains the standard Rational Summit/TM implicit and predefined fields as well as those other fields that are found in just about every task kind.
Domain: path Id: string Name: task_path Kind: string Kind_Path: path
These fields just report the implicit attributes of all tasks. The Name and Kind_Path fields are not displayed by this kind's task editor.
State: state State.sm
The meaning of the State field is described in detail in the following sections.
Priority: enum Unassigned Low Medium High Critical
The Priority field indicates how important it is, to the development team, to complete the task. In general, barring other dependencies, higher priority tasks should be worked on and completed before lower priority tasks. This field does not directly tell how important the task is to the "outside" (such as, to a customer). The Severity field is for that purpose.
Assigned: enum Unknownuser_defined_values
The Assigned field identifies the person responsible for working on the task.
Summary: string
The Summary field should contain a short, one line description of the purpose of the task. If the task is to fix some bug, the Summary should characterize what the bug is. If it is to add a new feature, it should describe the feature.
Description: text*
The Description field contains a more detailed description of what the task is about. Note that the Design_Log, Test_Log, Background, Symptoms, Test_Sequence, Workaround and Patch fields should be used for their respective purposes as opposed to dumping everything in the Description field. However, for small tasks, it may be more convenient to just use this field.
Parent: task_path Children
The Parent field for this task kind has no particular purpose at this time. However, it could be used to collect a group of related tasks together under some sort of "project" or "release" task kind. It represents a child's relationship to its parent task.
Children: task_path* Parent
The Children field keeps track of all the Document Change Tasks (dct) and Software Change Tasks (sct) associated with this change task. It represents this parent task's relationships to its children.
CmvcVersions: version*
The CmvcVersions field is identified in the task editor as the Version History Information: field. In general, change tasks do not have versions associated with them directly, so this field is not used. Instead, any versions are associated with the change tasks's DCT and SCT children tasks.
Development Information Group
The development information group contains those fields which are typically of interest to the software development team, on an on-going basis, for the life of a task. This data generally captures more detailed information concerning who's responsible for what, what's been done and what needs to be done.
Originator: enum Unknownuser_defined_values
The Originator field identifies the person who either created the task or was directly responsible for causing the task to be created. In either case, this person is often someone outside of the development team who wants to know when the task is resolved. For example, the Originator could be someone in the support department who has reported a bug that a customer discovered. The value for this field will be set automatically (to the creator of the task) if the post create task customization action is enabled for the task domain in which the new task is created.
Manager: enum Unknownuser_defined_values
The Manager field simply identifies the person who has management authority over the development team. This person typically wants to keep a little closer eye on how the task is progressing than the Originator cares to know.
Integrator: enum Unknownuser_defined_values
The Integrator field identifies the person responsible for integrating the changes made by the various developers on the team.
Tester: enum Unknownuser_defined_values
The Tester field identifies the person responsible for performing any system testing on the end product of the task.
Doc_Status: enum Unresolved Needs_Work No_Changes Updated Do_It_Later
The Doc_Status field just notes whether the task will require any changes to the documentation, and, if so, if the changes have been made. It just serves as a documentation check off list.
Test_Status: enum Unresolved Needs_Work No_Changes Updated Do_It_Later
The Test_Status field just notes whether the task will require any changes to the product's suite of regression tests, and, if so, if the changes have been made. It just serves as a regression test check off list.
Release_Version: enum Unknownuser_defined_values
The Release_Version field is identified in the task editor as the Release_Vers: field. It simply notes in which version of the released product the results of the task will first appear.
Estimated_Effort: string
The Estimated_Effort field is used to predict how much work the task will take. This information can be useful in determining schedules and workloads. It is up to the development team to decide what units to use to represent this effort, such as person-days or person-weeks.
Actual_Effort: string
The Actual_Effort field is used to record how much work the task actually took. This information can be used in conjunction with the Estimated_Effort field for tracking actual progress against a development plan.
Est_Release_Date: date
The Est_Release_Date field is identified in the task editor as the Est_Rel_Date: field. It records the estimated release date for the version of the product in which the results of the task are expected to be included. It is used to determine if the task is making progress in a timely fashion.
Cancel_Code: enum Unresolved Not_Applicable Not_A_Problem Duplicate Not_Reproducible Bad_Idea Beyond_Scope Transferred
The Cancel_Code field is meaningful only for tasks that have transitioned into the Canceled state. It notes, in a simple, precise code, why the task was canceled.
Cancel_Reason: text*
The Cancel_Reason field is also only meaningful for tasks that have transitioned into the Canceled state. It can be used to provide a more detailed explanation for why the task was canceled than is indicated by the Cancel_Code field as well as any auxiliary information. For example, for a duplicated task, this field can reference the other task.
Design_File: path
The Design_File field can be used to refer to a file containing extensive design information about the task. Limited amounts of design information should just be placed in the Design_Log field.
Design_Log: text*
The Design_Log field contains design information of limited quantities. It can also include design review comments from other members of the development team.
Test_File: path
The Test_File field can be used to refer to a file (or directory) containing extensive regression test information pertaining to the task. This can take the form of either descriptions of the types of regression tests that should be developed or the test scripts themselves. Limited amounts of regression test information should just be placed in the Test_Log field.
Test_Log: text*
The Test_Log field contains regression test information of limited quantities. It can also include test review comments from other members of the development team and the (summarized) results of running the tests during the System_Test state.
Problem Report Information Group
The problem report information group contains those fields which typically capture more detailed historical or external data about a task. This information is especially useful for bug reporting as it tries to capture the precise circumstances under which the problem occurred.
Product_Area: enum Unknownuser_defined_values
The Product_Area field identifies the highest level of product classification within the development organization. Each product area may include many different (or closely related) products. Product areas are typically divided along major organizational boundaries.
Product: enum Unknownuser_defined_values
The Product field identifies the product to which the task is most closely related. Typically, one type of product is released (sold) independently of another product.
Product_Version: enum Unknownuser_defined_values
The Product_Version field notes which version of the product was used to create the problem which caused the task to be generated.
Component: enum Unknownuser_defined_values
The Component field names the piece (or area) of the product with which the task is most closely related.
Env_Version: enum Unknownuser_defined_values
The Env_Version field records which version of the execution or runtime environment was used to create the problem which caused the task to be generated.
Window_System: enum Unknownuser_defined_values
The Window_System field records which windows system was used to create the problem which caused the task to be generated.
Problem_Type: enum Unknownuser_defined_values
The Problem_Type field attempts to classify the type of problem reported. There are many possible classification schemes depending on the application.
Platform_HW: enum Unknownuser_defined_values
Platform_OS: enum Unknownuser_defined_values
The Platform_HW and Platform_OS fields identify the type of hardware and associated operating system that the product was running (hosted) on when the problem occurred.
Target_HW: enum Unknownuser_defined_values
Target_OS: enum Unknownuser_defined_values
The Target_HW and Target_OS fields identify the type of hardware and associated operating system that a result of the product was running on when the problem occurred. This is usually only meaningful for cross-compilers where the code is compiled on one machine and executed on another.
Severity: enum Undefineduser_defined_values
The Severity field indicates how important it is, to the person (or organization, such as, a customer) reporting the problem, to complete the task. It should give an idea of the hardship being suffered.
Scopus_ID: int External_ID: string
The Scopus_ID and External_ID fields are just two possible ways of referring to an "outside" source for additional information about the problem reported in the task. The Scopus_ID could be used to refer to an external bug tracking system and the External_ID could be used to refer to a particular customer's problem report.
Background: text*
The Background field contains miscellaneous information about the history of the problem reported via the task.
Symptoms: text*
The Symptoms field describes what actually happens when the problem occurs. Does the system hang, crash or display some error message.
Test_Pathname: path
The Test_Pathname field identifies a file (or directory) containing data which can be used to reproduce the problem. This could be in the form of a script to run, some source code to compile or other input data to be processed. The smaller the amount of test data, the better.
Test_Sequence: text*
The Test_Sequence field should describe the sequence of steps that must be taken to reproduce the problem. The simplest and least number of steps that generate the problem will have a greater chance of resolving the issue. However, remember that preciseness counts more than conciseness.
Workaround: text*
The Workaround field explains, if possible, how the user can bypass the problem and still achieve the desired end results. This may involve using different features of the product or modifying the user's input data (among other techniques).
Patch: text*
The Patch field describes, if possible, how the user can modify the product so that the problem no longer occurs.
Task History Information Group
The task history information group contains those fields which record significant events in the life of a task. These events are typically related to task state transitions. This information is especially useful for certain metric reporting which is designed to identify trends over time. All of these fields are automatically maintained by the task kind's state transition post actions and do not have to be manually updated.
Create_Date: date
The Create_Date field is used to record the time when the task first came into existence (that is, when the task enters the New state). The value for this field will only be set if the post create task customization action is enabled for the task domain in which the new task is created.
Start_Date: date
The Start_Date field is used to record the time when the developer first started to work on the task. It can be used in conjunction with the Act_Release_Date or Cancel_Date fields to provide a gross measurement of how much effort went into completing the task.
Act_Release_Date: date
The Act_Release_Date field is identified in the task editor as the Act_Rel_Date: field. It records the actual time when the task was completed and released with the product. This field is only meaningful for tasks that have transitioned into the Completed state.
Cancel_Date: date
The Cancel_Date field is only meaningful for tasks that have transitioned into the Canceled state. It merely records when the task was canceled.
Task_History: text*
The Task_History field is a cumulative log of all task state transitions. For every such transition, it records the current date and time, the user who initiated it, and the name of the new state. This history of state transitions is only maintained if certain task domain customization actions are enabled.
Task Initialization Template
The following fields are initialized to the corresponding values when a change task is created:
Priority: Unassigned State: New
Other fields which may also prove useful to initialize with the appropriate user defined values include:
Integrator:user_defined_values
Tester:user_defined_values
Product_Area:user_defined_values
Product:user_defined_values
States
The state machine for a change task includes the following states.
New Pending Assigned Design Implement Integrate System_Test Completed Canceled
The significance of each state is as follows.
New
The New state is simply the initial starting state for all tasks. A task should only be in this state for a short while until the manager decides if the task should be either 1) worked on immediately (to the Assigned state), 2) worked on later (to the Pending state), or, 3) canceled for some reason (to the Canceled state).
Pending
A task in the Pending state is waiting to be worked on at some point in the future. This is typically for tasks destined for subsequent releases of the product that are planned, but not currently in progress, or for tasks for which there are no commitments to other than to remember to consider them for potential improvements to the product. At that time, the manager may decide to 1) give the task to a developer to work on (to the Assigned state), or, 2) based on new knowledge or circumstances, cancel the task (to the Canceled state).
Assigned
The Assigned state is for a task that has been approved by the manager for work by a particular developer. Such a task is basically queued up, waiting for the developer's attention. The order in which assigned tasks are chosen by a developer to work on is influenced by several factors, such as 1) dependencies between tasks, 2) availability of resources, 3) the importance of a task (as indicated by its Priority field), and, 4) scheduling requirements. The developer may choose to work on more than one task at a time depending on the developer's style and other practical factors. After choosing the next assigned task to receive attention, the developer may decide to 1) do some design work on it (to the Design state), 2) start implementing it (to the Implement state) or 3) cancel the task for any of a number of reasons (to the Canceled state). In addition, when circumstances warrant, the developer may decide (presumably with the advise and consent of the manager) to indefinitely postpone additional work on the task (to the Pending state).
Design
A task is in the Design state when the developer is working on how the job is to be accomplished. This may include analyzing the problem and its requirements, specifying new or modified user interfaces, defining program interfaces, determining the impacts of any proposed changes, designing algorithms or otherwise figuring out how to implement the changes. Once these issues have been resolved, the developer may decide to start implementing the changes (to the Implement state). Alternatively, the developer may temporarily postpone work on the task (to the Assigned state) due to higher priority tasks. A task may also be moved back to the Assigned state because the manager decided to reassign it to another developer.
Implement
A task is in the Implement state while the developer is actually making the necessary changes such as modifying source code, writing documentation or performing unit testing. When all changes have been made and tested, the developer submits the task to the final product integration process (to the Integrate state). Alternatively, as in the Design state, the task my be returned to the Assigned state.
Integrate
The Integrate state is for a task which has been fully implemented (at least in theory) and is ready to be integrated with all the other changes (that is, tasks) that are going into the release of the product. The integration step is performed by the integrator. Depending on the product build policies and conventions of the development team, it may be that, at this stage, all controlled object versions associated with a change task and all of its dependent dct and sct tasks are accepted into the final product build tower for full and complete integration. Alternatively, it may be that an incremental acceptance of version changes is all that is necessary. In either case, if the integration is successful, then the integrator may send the task off to be tested (to the System_Test state). If the integration fails for some reason, then the task is returned to the developer to be fixed (to the Implement state). In addition, the manager can decide to reassign the task (to the Assigned state).
System_Test
A task enters the System_Test state when it is ready to be tested with all the other changes (that is, tasks) which are to be included with the release of the product. At this point the individual filling the tester role takes over and runs the various regressions tests against the end product. If the tests pass, the tester gives the seal of approval and confirms that the task is finished (to the Completed state). However, if any tests fail, the tester returns the task to the developer to be fixed (to the Implement state). In addition, the manager can decide to reassign the task (to the Assigned state).
Completed
When a task is fully designed, implemented, integrated, tested and documented, it can enter the Completed state. At this point, the results of the task can be delivered to the customer whenever it is appropriate to do so. However, as a final resort, in case some last minute bug was found in the product before shipment to customers, the task can be pulled out of the Completed state and put into the Pending state to be worked on some more.
Canceled
The Canceled state is for a task whose originally intended purpose has been determined to be of no useful value to the development organization and all further work on it is terminated. This is typically the case when a request for change has already been done, is inappropriate, or is due to a misuse of the product. Although this is normally a final state for a task, like the Completed state, the manager can revive it (to the Pending state).
State Transitions
The following state transitions, along with their preconditions and post actions are supported by the change task kind.
Preconditions and Post Actions
The precondition and post actions of the change task kind perform the following functions. For the first action, Assigned_OK, the details of an action clause are explained.
Assigned_OK
In general, the Assigned_OK action verifies that the Assigned field is properly defined. More specifically, it issues the following action clause directives and csh shell commands.
action Assigned_OK ## Defines the name of the action clause and the ## beginning of its definition. (Action directive) options Message_Window Retain_Busy ## Causes standard output and error messages to be ## displayed in the Apex Message Window and sets ## the mouse cursor to the "Busy" icon for the ## duration of the action clause. (Action ## directive) ## Start of csh program --- cd <task.Kind_Path> ## Changes the current working directory to the ## kind directory of the task whose state is ## being changed. Not always necessary, but it is ## a good practice to start in a known place. echo "" echo ---- Precondition Assigned_OK ---- ## Outputs introductory message to Message Window. set result = 0 if ( "<task.Assigned>" == "" || \ "<task.Assigned>" == "Unknown" ) then echo "*** Assigned: must be defined before ..." set result = 1 endif ## Checks if the current value of the task's ## Assigned field is empty or the Unknown value, ## and, if so, generates an error message. Sets ## the result code appropriately. apex_display perform unbusy <ALIAS_KEY> ## Changes the mouse cursor back to its normal icon. exit $result ## Returns result of precondition test. If the test ## succeeds, a result of zero (0) must be returned. ## Any other value implies failure. ## End of csh program --- end_action Assigned_OK ## Identifies the end of the action clause (Action ## directive)
Assigned
Canceled_OK
Verifies that the Cancel_Code, Doc_Status and Test_Status fields are properly resolved.
Canceled
Sets the Start_Date field to the current date (if it was not already set).
Sets the Cancel_Date field to the current date.
Sets the Act_Release_Date field to "".
Sends email to Originator and Manager.
Completed_OK
Verifies that the Release_Version field is properly defined.
Verifies that ALL child tasks have either been Completed or Canceled.
Completed
Sets the Act_Release_Date field to the current date.
Sets the Cancel_Code field to Not_Applicable.
Sets the Cancel_Date field to "".
Sends email to Originator and Manager.
Implement
Does nothing special. It is just a place holder.
Integrate_OK
Verifies that the Integrator field is properly defined.
Verifies that all child sct tasks have either been Completed or Canceled.
ntegrate
Pending
Re_Implement
Reconsidered
Started
Sets the Start_Date field to the current date (if it was not already set).
Stop_Integrate
Sends email to Integrator, Manager and Assigned.
Stop_Test
Sends email to Tester, Manager and Assigned.
System_Test_OK
Verifies that the Tester field is properly defined.
Verifies that the Doc_Status and Test_Status fields are properly resolved.
System_Test
Task Editor
In addition to displaying the values of its various fields, the change task kind's task editor contains the following button actions.
On the Related Tasks page, the New SCT Task... button invokes the supporting script, create_new_sct.csh, from the task kind's directory. This script creates a new software change task (sct task kind) as a child of the current task and then visits the new child. The New DCT Task... button invokes the supporting script, create_new_dct.csh, from the task kind's directory. This script creates a new documentation change task (dct task kind) as a child of the current task and then visits the new child. The New Child... button invokes the File > New > New Task command with the current task initialized as the new parent. The Visit button performs the Navigate > Visit command on the task selected from the values either in the Children field or the Parent field.
On the Version History page, the Visit Current button will execute the Navigate > Visit command on the current version of the selected version in the CmvcVersions (alias Version History Information) field. The Show Version Image button executes (the equivalent of) the Control > Show > Version Image command on the selected version from the CmvcVersions field.
On the Design page, the Visit button will execute the Navigate > Visit command on the value of the Design_File field.
On the Test page, Visit button executes the Navigate > Visit command on the value of the Test_File field.
Supporting Scripts
notify.csh
The notify.csh script is used to send email messages to members of the development team. It has the following interface:
notify.csh [ -assignedassigned
] [ -new_statenew_state
] [ -old_stateold_state
] [ -cancel_codecancel_code
] [ -summarysummary
] { -toto
} -tasktask
Only the -task option is required.
All of its options, with the exception of the -to option, are merely used to pass the values of the similarly named task fields to the program. These options are used to format the subject and body of the message. The -to option (of which there may be more than one) is used to identify the recipients of the message. The script removes duplicate recipients. It also does not bother to send the message to the sender (whomever invoked this script).
In the generic version of the task kind, this script does not actually send the message. Instead it does all the analysis and formatting, and then just displays what it would send on the Message Window, if anything. It is currently set up to use the standard Mail utility, if enabled. Of course, other customer-dependent mail programs can be substituted.
create_new_dct.csh
The create_new_dct.csh script should only be invoked from the task editor. When so activated, it creates a new documentation change task (dct task kind) as a child task of the task being viewed in the editor. The child task is created in the same task domain as its parent. It also inherits the same values for its Assigned and Priority fields. After a successful creation, the new task is visited.
create_new_dct.csh
The create_new_sct.csh script should only be invoked from the task editor. When so activated, it creates a new software change task (sct task kind) as a child task of the task being viewed in the editor. The child task is created in the same task domain as its parent. It also inherits the same values for its Assigned, Priority and Integrator fields. After a successful creation, the new task is visited.
Documentation Change Task Kind
The generic documentation change task kind is called dct.
Policy Switches
The dct task kind defines the following prefix and suffix for its part of the task id generation policy:
Prefix: D Suffix:
This, of course, can be changed to whatever is desired.
Task Fields
The dct task kind supports the following fields. The meaning of each field is described after its name and associated field type. Note that, except where otherwise indicated, the name of a field in the dct task editor is identical to its formal name in the task kind Fields file.
Domain: path Id: string Name: task_path Kind: string Kind_Path: path
These fields just report the implicit attributes of all tasks. The Name and Kind_Path fields are not displayed by this kind's task editor.
State: state State.sm
The meaning of the State field is described in detail in the following sections.
Priority: enum Unassigned Low Medium High Critical
The Priority field indicates how important it is, to the development team, to complete the task. In general, barring other dependencies, higher priority tasks should be worked on and completed before lower priority tasks. Its value is inherited from its parent task initially.
Assigned: enum Unknownuser_defined_value
The Assigned field identifies the person responsible for working on the task. Its value is inherited from its parent task initially.
Document: enum Unknownuser_defined_values
The Document field identifies the product document that needs updating.
Tech_Writer: enum Unknownuser_defined_values
The Tech_Writer field identifies the person responsible for editing the documentation files.
Document_File: path
The Document_File field can be used to reference the particular file that contains the documentation that needs to be changed. For multiple files it can reference a common directory. It could also be used to reference the file containing the developer's rough draft input to the tech writer.
Summary: string
The Summary field should contain a short, one line description of the purpose of the task. If the task is to fix some bug, the Summary should characterize what the bug is. If it is to add a new feature, it should describe the feature.
Log: text*
The Log field can contain multiple types of information pertaining to the Documentation Change Task such as 1) the developer's instructions to the tech writer on how to update the documentation, 2) questions from the tech writer about the developer's input or requests for additional information, 3) document section references for locating the changes, and, 4) corrections to the tech writer's updated documentation that are discovered when the material is proofread.
Parent: task_path Children
The Parent field for a Document Control Task (dct kind) task should identify the task's master change task (change kind). It represents the child's relationship to its parent task.
Children: task_path* Parent
The Children field for a Documentation Change Task is currently not defined for any particular purpose. It represents a parent task's relationships to its children.
CmvcVersions: version*
The Documentation Change Task kind (dct) does not currently presume that documentation files are controlled, versioned and integrated the same way as is done for other product source files. In this case the CmvcVersions field is not used for this task kind. If documentation files are controlled in a similar manner, then their versions should be recorded in this field.
Task_History: text*
The Task_History field is a cumulative log of all task state transitions. For every such transition, it records the current date and time, the user who initiated it, and the name of the new state. This history of state transitions is only maintained if certain task domain customization actions are enabled. See the "Metrics and Reports" section of the Rational Summit/TM Command Reference for details.
Task Initialization Template
The following fields are initialized to the corresponding values when a dct task is created:
State: New
Other fields which may also prove useful to initialize with the appropriate user defined values include:
Document:user_defined_value
Document_File:user_defined_path
Tech_Writer:user_defined_value
State Machine
The state machine for a dct task includes the following states.
New Write Typeset Proofread Completed Canceled
The state machine for a dct task includes the following states.
New
The New state is simply the initial starting state for all tasks. A task should only be in this state for a short while until the developer decides to start writing up the documentation changes for the tech writer (to the Write state). Alternatively, after creating the task, the developer may then realize that the documentation does really need any changes made to it anyway and the task should be discarded (to the Canceled state).
Write
A dct task should be in the Write state while the developer is figuring out how the documentation should be changed. These changes may be in the form of a rough draft, selected editorial corrections, or marked up copies of the old documentation. Once the documentation changes are done, the task is handed off to the tech writer (to the Typeset state). Alternatively, again the developer may choose to abandon the changes after further research (to the Canceled state).
Typeset
In the Typeset state a dct task is being worked on by the tech writer, making the appropriate changes to the documentation files. When the files have been updated to the tech writer's satisfaction, the task is given back to the developer for verification (to the Proofread state). However, if the tech writer has questions about how to interpret the developer's instructions (or otherwise complete the job), the task can be returned to the developer for the answers (to the Write state). In addition, the developer can take the task back from the tech writer to make more changes (to the Write state).
Proofread
While in the Proofread state, a dct task is waiting for the developer to review the results of the tech writer for accuracy. If all is well, the task is finished (to the Completed state). If not, then the developer has to go do some more work on the documentation (to the Write state).
Completed
When all the necessary documentation changes have been written, typeset and proofread, a dct task can be moved to the Completed state. However, the results of this labor are NOT authorized for publication (that is, public release) until the task's parent master change task has been completed. Until that time, the dct task can be reconsidered by the developer for additional work (to the Write state).
Canceled
The Canceled state simply records the fact that a dct task is no longer considered to be of any value to the development team. However, it can be revived by the developer if circumstances change and make it useful again (to the Write state).
State Transitions
The following state transitions, along with their preconditions and post actions are supported by the dct task kind
Preconditions and Post Actions
The precondition and post actions of the dct task kind perform the following functions.
Completed
Proofread
Re_Write
Sends email to Assigned and Tech_Writer.
Reconsidered
Typeset_OK
Verifies that the Tech_Writer field is properly defined.
Typeset
Task Editor
In addition to displaying the values of its various fields, the dct task kind's task editor contains the following button actions.
In the unpaged section of the task editor, the Visit button will execute the Navigate > Visit command on the value of the Document_File field.
On the Related Tasks page, the New Child... button invokes the File > New > New Task command with the current task initialized as the new parent. The Visit button performs the Navigate > Visit command on the task selected from the values either in the Children field or the Parent field.
On the Version History page, the Visit Current button will execute the Navigate > Visit command on the current version of the selected version in the CmvcVersions (alias Version History Information) field. The Show Version Image button executes (the equivalent of) the Control > Show > Version Image command on the selected version from the CmvcVersions field.
Supporting Scripts
notify.csh
The Documentation Change Task kind uses the same notify.csh script as the master change task kind.
Software Change Task Kind
The generic software change task kind is called sct.
Policy Switches
The sct task kind defines the following prefix and suffix for its part of the task id generation policy:
Prefix: S Suffix:
This, of course, can be changed to whatever is desired.
Task Fields
The sct task kind supports the following fields. The meaning of each field is described after its name and associated field type. Note that, except where otherwise indicated, the name of a field in the sct task editor is identical to its formal name in the task kind Fields file.
Domain: path Id: string Name: task_path Kind: string Kind_Path: path
These fields just report the implicit attributes of all tasks. The Name and Kind_Path fields are not displayed by this kind's task editor.
State: state State.sm
The meaning of the State field is described in detail in the following sections.
Priority: enum Unassigned Low Medium High Critical
The Priority field indicates how important it is, to the development team, to complete the task. In general, barring other dependencies, higher priority tasks should be worked on and completed before lower priority tasks. Its value is inherited from its parent task initially.
Assigned: enum Unknownuser_defined_values
The Assigned field identifies the person responsible for working on the task. Its value is inherited from its parent task initially.
Integrator: enum Unknownuser_defined_values
The Integrator field identifies the person responsible for integrating the changed versions associated with the task into the common pre-release build towers. Its value is inherited from its parent task initially.
Summary: string
The Summary field should contain a short, one line description of the purpose of the task. If the task is to fix some bug, the Summary should characterize what the bug is. If it is to add a new feature, it should describe the feature.
Log: text*
The Log field can contain various types of information pertaining to the Software Change Task such as specific implementation notes or integration problems reported by the integrator.
Parent: task_path Children
The Parent field for a Software Control Task (sct kind) task should identify the task's master change task (change kind). It represents the child's relationship to its parent task.
Children: task_path* Parent
The Children field for a Software Change Task is currently not defined for any particular purpose. It represents a parent task's relationships to its children.
CmvcVersions: version*
The Software Change Task kind (sct) records the controlled versions that have been updated in this pass through the implementation, integration cycle. It need not contain all the changes that are required to complete the parent master change task. However, its set of changes should be internally consistent when in the Integrate state. For example, they should compile error-free with the rest of the source files in the product.
Task_History: text*
The Task_History field is a cumulative log of all task state transitions. For every such transition, it records the current date and time, the user who initiated it, and the name of the new state. This history of state transitions is only maintained if certain task domain customization actions are enabled. See the "Metrics and Reports" section of the Rational Summit/TM Command Reference for details.
Task Initialization Template
The following fields are initialized to the corresponding values when an sct task is created:
State: New
State Machine
The state machine for an sct task includes the following states.
New Implement Test Integrate Completed Canceled
The state machine for an sct task includes the following states.
New
The New state is simply the initial starting state for all tasks. A task should only be in this state for a short while until the developer decides to start implementing the software changes (to the Implement state). Alternatively, after creating the task, the developer may then realize that the software does not really need to be changed and the task should be discarded (to the Canceled state).
Implement
An sct task should be in the Implement state while the developer is coding the software. Once the software changes are done, they are unit tested (to the Test state). Alternatively, again the developer may choose to abandon the changes after further research (to the Canceled state).
Test
While in the Test state, the software changes are verified that they do indeed accomplish the desired objectives. If not, the developer must do some more programming (to the Implement state). If everything works as expected, the changes are ready to be integrated (to the Integrate state).
Integrate
In the Integrate state, an sct task is being worked on by the integrator. The changes associated with the task are combined with the work of other sct tasks. If all changes compile correctly and possibly pass a limited functional test, then the integrator notes that the task is done (to the Completed state). If not, then the task is returned to the developer for resolution (to the Implement state).
Completed
An sct task belongs in the Completed state once all its changes have been successfully integrated. Since, in general, it is difficult to unintegrate the changes, there is no way out of this state. If there is a need to back out the changes, a new sct task should be created for that job.
Canceled
The Canceled state simply records the fact that an sct task is no longer considered to be of any value to the development team. However, it can be revived by the developer if circumstances change and make it useful again (to the Implement state).
State Transitions
The following state transitions, along with their preconditions and post actions are supported by the sct task kind.
Preconditions and Post Actions
The precondition and post actions of the sct task kind perform the following functions.
Completed
Integrate_OK
Verifies that the Integrator field is properly defined.
Integrate
Re_Implement
Task Editor
In addition to displaying the values of its various fields, the sct task kind's task editor contains the following button actions.
On the Related Tasks page, the New Child... button invokes the File > New > New Task command with the current task initialized as the new parent. The Visit button performs the Navigate > Visit command on the task selected from the values either in the Children field or the Parent field.
On the Version History page, the Visit Current button will execute the Navigate > Visit command on the current version of the selected version in the CmvcVersions (alias Version History Information) field. The Show Version Image button executes (the equivalent of) the Control > Show > Version Image command on the selected version from the CmvcVersions field.
Supporting Scripts
notify.csh
The Software Change Task kind uses the same notify.csh script as the master change task kind.
Customization
Only a few customizations need be performed to turn the generic change management task kinds into usable tools. They are presented here. Of course, many additional customizations are possible to make the task kinds look and behave in ways that are more familiar to the development team. Such customizations are encouraged but only after the original task kinds are well understood. Take them for a test drive, see how they handle, and then start remolding, repainting and rewiring the model.
First, the various task fields of type enum should be examined to determine which enumeration values are most meaningful to the development team. In particular, the fields described above as having user_defined_values, such as the Assigned field, need to be filled in. Other enumerated fields that are not identified as having user_defined_values should also be examined to verify that their values are appropriate. For example the values of the Priority field may not match those already in practice by the team and should probably be changed. Be careful, however when changing predefined values to check the action clauses to see if they reference the value and must also be updated. This currently applies only to the following fields.
Task Kind
Field Name
change Assigned
Doc_Status
Integrator
Cancel_Code
Release_Version
Test_Status
Tester
dct Tech_Writer
set Integrator
The task field enumeration values are defined in the task kinds' Fields files. The action clauses are defined in the State.actions files.
Second, the task initialization templates should be customized to properly initialize the enumerated fields that have user_defined_values. These are referenced in the task kinds' initial.task files.
Third, the supporting script, notify.csh, should be customized to use the appropriate electronic mail system for sending notification messages to team members.
Finally, if desired, the task domain customization actions should be enabled in order to collect various task history metrics. Seethe Rational Summit/TM Command Reference document for details.
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |