| <html> |
| <head> |
| <title>Using EPF with a Version Control System</title> |
| <style> |
| td ul { |
| margin-bottom: 0px; |
| padding-left: 1.2em; |
| margin-left: 0px; |
| } |
| |
| h1, h2, h3 { |
| font-family: Arial; |
| } |
| |
| table { |
| border-collapse: collapse; |
| } |
| |
| td { |
| vertical-align: top; |
| } |
| |
| .note { |
| font-size: 0.8em; |
| color: graytext; |
| } |
| |
| </style> |
| </head> |
| <body> |
| <h2>Using Eclipse Process Framework Composer with a Version Control |
| System</h2> |
| Version 1.01 |
| |
| <h3>Abstract:</h3> |
| |
| <p>The initial Eclipse Process Framework (EPF) Composer tool does not |
| provide native support for version control systems, such as the IBM® |
| Rational® ClearCase® configuration management tool, the open |
| source version control system Concurrent Versions System (CVS) or other |
| version control systems.</p> |
| |
| <p>This document describes some techniques to facilitate using EPF |
| Composer with a version control system. Most examples provided here |
| relate to usage of IBM Rational ClearCase, as it was the version control |
| system used before donation of source code and process content to |
| Eclipse organization. As this community tries out using EPF Composer |
| with other version control systems, please provide feedback so we can |
| update this document.</p> |
| |
| <h3>Table of Contents</h3> |
| <ol> |
| <li><a href="#overview">Overview of EPF Composer Files</a> |
| <ol> |
| <li><a href="#library"><code>library.xmi</code></a></li> |
| <li><a href="#plugin"><code>plugin.xmi</code></a></li> |
| <li><a href="#element"><code><method content element>.xmi</code></a></li> |
| <li><a href="#model"><code>model.xmi</code></a></li> |
| <li><a href="#content"><code>content.xmi</code></a></li> |
| </ol> |
| </li> |
| <li><a href="#locate">Locate your Library and Prime It Appropriately</a> |
| <ol> |
| <li><a href="#extend">You want to Extend OpenUP/Basic</a></li> |
| <li><a href="#create">You want to Create Your own Library</a></li> |
| <li><a href="#cc1">A note for IBM Rational ClearCase Users</a></li> |
| <li><a href="#proj">A note about the .project File</a></li> |
| <li><a href="#put">Put all files being developed under version control</a></li> |
| </ol> |
| </li> |
| <li><a href="#writeable">Ensure the Appropriate Files Are Writable</a> |
| <ol> |
| <li><a href="#m1">Method 1 (Recommended): Work directly in your</a></li> |
| <li><a href="#m2">Method 2: Work in a copy of your controlled</a></li> |
| </ol> |
| </li> |
| <li><a href="#refresh">Extremely Important: Refresh EPF Composer's Memory Cache</a></li> |
| <li><a href="#control">Make Both Applications Think They Are in Control</a> |
| <ol> |
| <li><a href="#rename">Rename a Method Element</a></li> |
| <li><a href="#cc2">For ClearCase Users</a></li> |
| </ol> |
| </li> |
| <li><a href="#consistency">Maintain Consistency of Method Library References</a> |
| <ol> |
| <li><a href="#cipl">Checking in <code>plugin.xmi</code> or <code>library.xmi</code></a></li> |
| <li><a href="#cim">Checking in <code>model.xmi</code></a></li> |
| </ol> |
| </li> |
| <li><a href="#conflict">Some Ways to Minimize Shared File Conflicts</a></li> |
| <li><a href="#cc3">For ClearCase Users</a></li> |
| <li><a href="#a">Appendix A: Based on Your Actions, What Files Change?</a></li> |
| <li><a href="#b">Appendix B: For each EPF Composer File, What Changes Affect</a></li> |
| </ol> |
| |
| <h2>Using EPF Composer with a Version Control System</h2> |
| |
| <h1 class="content"><a name="overview">1. Overview of EPF Composer |
| Files</a></h1> |
| |
| <p>Before we delve into the details of using EPF Composer with a version |
| control system, you should be aware of some files play a key role in the |
| EPF Composer library. These need to be carefully controlled because they |
| contain information that must be kept in synch with other files in your |
| library. They are referenced often in this document. The following |
| summarizes those files and the role they play in your EPF Composer |
| library. For specific information on what changes affect what EPF |
| Composer <code>.xmi</code> file, see <a href="#a">Appendix A: Based on |
| Your Actions, What Files Change?</a> or <a href="#b">Appendix B: For each |
| EPF Composer File, What Changes Affect the File?</a>.</p> |
| |
| <h2 class="content"><a name="library">1.1 <code>library.xmi</code></a></h2> |
| |
| <p>There is one <code>library.xmi</code> file for each method library. |
| This file contains a reference to every plug-in in your EPF Composer |
| library. It also contains the details of what is included in each |
| configuration, including which content packages, which process packages, |
| and which processes (capability patterns and delivery processes) are |
| included, as well as the specification of what's included in each view. |
| When you create new packages, EPF Composer does not modify this file, |
| but this file is updated if you create a new process. This file is |
| shared by all plug-ins in your EPF Composer library, so you need to be |
| especially careful to coordinate changes being made by different |
| individuals.</p> |
| |
| <h2 class="content"><a name="plugin">1.2 <code>plugin.xmi</code></a></h2> |
| |
| <p>There is one <code>plugin.xmi</code> file for each plug-in. This file |
| contains a reference to every content element in the plug-in, as well as |
| the presentation names, brief descriptions, and relationships for each |
| element, such as guidance, inputs or outputs (tasks), performing role |
| (tasks), work products responsible for (role) etc. It also contains the |
| definition of what is included in each standard category as well as the |
| definition and contents of each custom category. When more than one |
| person works on a plug-in, you need to be especially careful about |
| coordinating changes to this file and any files it references.</p> |
| |
| <h2 class="content"><a name="element">1.3 <code><method content |
| element>.xmi</code></a></h2> |
| |
| <p>There is one file per method content element. It contains the |
| descriptive text for the method content element for all fields except |
| the name, presentation name, and brief description. The file name |
| (<method content element>) is the same as the 'name' field for the |
| element. (One exception to this: if you create a second method content |
| element with the same name and that element is located in the same |
| directory in your library, then EPF Composer will append '2' to the end |
| of the actual filename. The appended '2' will not appear in the name |
| field in EPF Composer.)</p> |
| |
| <h2 class="content"><a name="model">1.4 <code>model.xmi</code></a></h2> |
| |
| <p>There is one <code>model.xmi</code> file for each process (capability |
| pattern or delivery process). This file contains a reference to the |
| descriptors (role, task, and work product), as well as the names and |
| brief descriptions for each of them. It also contains the diagrams. |
| However, the brief description and presentation name for the process |
| itself is kept in the <code>plugin.xmi</code>.</p> |
| |
| <h2 class="content"><a name="content">1.5 <code>content.xmi</code></a></h2> |
| |
| <p>There is one <code>content.xmi</code> file for each process |
| (capability pattern or delivery process). This file contains the |
| descriptive text for the descriptors of the process elements, with the |
| exception of the names, presentation names and brief descriptions.</p> |
| |
| |
| <h1 class="content"><a name="locate">2. Locate your Library and |
| Prime It Appropriately</a></h1> |
| |
| <p>Now let's get started. Before you can set up your version control |
| system to support your Method Library, you need to decide where you want |
| to locate your method library.</p> |
| |
| <p>Next, you may need to prime your library. If you want to use the |
| Method Library that is provided with EPF Composer (OpenUP), rather than |
| create all of your method content from scratch, then you also need to |
| prime your library with the bundled library.</p> |
| |
| <h2 class="content"><a name="extend">2.1 You Want to Extend OpenUP/Basic</a></h2> |
| |
| <p>If you want to use the Method Library that is provided with EPF |
| Composer, you will need all of the files in the <code>\library</code> |
| directory (located in the directory where you unzipped EPF Composer) to |
| be in the same location as all of the files that you will create as part |
| of your own plug-ins.</p> |
| |
| <p>We suggest that you make a copy of the <code>\library</code> |
| directory and place it where you want your controlled source. Also place |
| the <code>library.xmi</code> file (<code>\library\library.xmi</code>) |
| under source code control, since you will need to modify this file.</p> |
| |
| <p>EPF Composer users will typically have all plug-ins that are bundled |
| with EPF Composer locked, to remind that these files should not be |
| changed. We suggest that you keep them locked. There is no need to |
| control the source of the EPF Composer library shipped with the product, |
| with the exception of <code>library.xmi</code>. You should control the |
| source for all of the plug-ins that you create. EPF Composer creates a |
| separate directory for each plug-in, so it will be easy for you to |
| distinguish your source files from those that were shipped with EPF |
| Composer.</p> |
| |
| <p>When you start EPF Composer, you just need to point it to the |
| directory where your controlled <code>library.xmi</code> file exists.</p> |
| |
| <p>Differently from EPF Composer users, EPF project committers have |
| write access to CVS repositories and are expected to source control the |
| plug-ins available in order to develop and maintain their contents.</p> |
| |
| <h2 class="content"><a name="create">2.2 You Want to Create Your own |
| Library</a></h2> |
| |
| <p>If you want to create your own method content entirely from scratch |
| using EPF Composer and are not interested in using any of the supplied |
| method content, then you just need to point EPF Composer to the |
| directory where you want your library files to exist (Use the menu item |
| File > New > Method Library in EPF Composer).</p> |
| |
| <h2 class="content"><a name="cc1">2.3 A Note for IBM Rational |
| ClearCase Users</a></h2> |
| |
| <p>You cannot successfully use a dynamic view with EPF Composer. You |
| need to create a snapshot view.</p> |
| |
| <h2 class="content"><a name="proj">2.4 A Note about the .project |
| File</a></h2> |
| |
| <p>When you start EPF Composer, it will create a .project file in the |
| directory where your controlled <code>library.xmi</code> file exists. |
| You should not place this .project file under version control since the |
| tool will create one on each user's workspace.</p> |
| |
| <h2 class="content"><a name="put">2.5 Put all Files being |
| Developed under Version Control</a></h2> |
| |
| <p>As files and directories are added to your method library, place them |
| under version control.</p> |
| |
| |
| <h1 class="content"><a name="writeable">3. Ensure the Appropriate Files |
| Are Writable</a></h1> |
| |
| <p>Whenever you make changes using EPF Composer that cause changes to |
| the underlying files for your Method Library, those files must be |
| writable. Due to the way the EPF Composer is designed, more than one |
| file may need to be modified when you make a change. (See <a href="#a">Appendix |
| A: Based on Your Actions, What Files Change?</a> for a list of actions |
| that cause this situation.) Many version control systems keep the |
| controlled files in your file system read-only unless you have unlocked |
| or checked out the files. Before you can make changes in EPF Composer |
| you need to guarantee that the files you will be modifying are writable. |
| There are two methods you can use to accomplish this.</p> |
| |
| <h2 class="content"><a name="m1">3.1 Method 1 (Recommended): Work |
| directly in your controlled source library</a></h2> |
| |
| <p>You can point EPF Composer directly to your controlled source (e.g., |
| to your snapshot from IBM Rational ClearCase or to your working |
| directory from CVS). When you want to make a change in EPF Composer, you |
| need to ensure that the files EPF Composer needs to modify are writable. |
| This typically means checking out the files in your version control |
| system.</p> |
| |
| <p>When you first start EPF Composer, you are asked for the location of |
| the method library. You should point EPF Composer to your library |
| snapshot, that is, to the directory that contains the <code>library.xmi</code> |
| file.</p> |
| |
| <p><b>Pros:</b> This method is the simplest. There is no need to |
| synchronize your workspace with your controlled source, as in Method 2 |
| below. Another advantage to this method is that it enforces proper |
| version control because you must obtain proper control over the files |
| you need to modify before you make any changes.</p> |
| |
| <p><b>Cons:</b> You may find it frustrating to need to continually check |
| out files before you can make any changes. If you can check out all of |
| the files in the plug-in you will be working in, you can minimize the |
| files you need to check out before you can proceed with your work; |
| however, you may not always be able to do this. Additionally, you cannot |
| easily see the changes that are made to the files you update. Some |
| errors can be easily caught by making such a comparison. For instance, |
| if someone accidentally dragged/dropped an item from the library view |
| into a rich text view, a link is created. If this was done |
| inadvertently, the user may not have noticed the creation of the link. |
| The comparison will point out the incorrect change.</p> |
| |
| <h2 class="content"><a name="m2">3.2 Method 2: Work in a copy of |
| your controlled source library</a></h2> |
| |
| <p>You can make a copy of your controlled source from your version |
| control system; make all of the files writable, and point EPF Composer |
| to this copy for the Method Library. When you want to make a change, you |
| still need to understand what files will be changed and obtain proper |
| control over these files (e.g., check them out of your version control |
| system) so that no one else will update them while you are updating |
| them. Once you've made your changes, you can compare the controlled |
| source with your copy to discover what files changed using a directory |
| comparison tool such as Beyond Compare® from Scooter Software (<a |
| href="http://www.scootersoftware.com/">www.scootersoftware.com</a>). |
| Copy the files that changed over to your source control library and |
| check these files into your version control system.</p> |
| |
| <p>When you first start EPF Composer, you are asked for the location of |
| the method library. You should point EPF Composer to your copy of your |
| controlled source library, that is, to the directory that contains the <code>library.xmi</code> |
| file.</p> |
| |
| <p><b>Pros:</b> Since all of the files are writable, EPF Composer will |
| allow any change. When you are just experimenting in your 'sandbox' and |
| do not intend to make your changes permanent, this can be quite useful. |
| This method is also useful if you want to compare the changes you have |
| made with the current source in your source library before checking in |
| your changes.</p> |
| |
| <p><b>Cons: </b>The disadvantage to this method is that there is more |
| manual work involved in copying files back and forth to ensure that your |
| copy of the source library is up-to-date. There's also the tendency to |
| forget to check out the files from your version control system before |
| you make changes. This could lead to conflicts when you try to check |
| these files back in because someone else may have modified them while |
| you were making your changes. This is especially true for <code>library.xmi</code> |
| or <code>plugin.xmi</code>.</p> |
| |
| <p><b>Caution:</b> We offer this method as an alternative because there |
| are times when it is useful. However, if you use this method to make |
| changes to controlled source, <b>you must be very careful</b> to ensure |
| that you check out the files you need and ensure that no one has changed |
| them in your source library since you initially made your copy of these |
| files.</p> |
| |
| |
| <h1 class="content"><a name="refresh">4. Extremely Important: Refresh |
| EPF Composer's Memory Cache</a></h1> |
| |
| <p>When you open a method library in EPF Composer, some of the |
| information contained in the source files is read into memory. If you |
| update the files in your Method Library outside of EPF Composer, you |
| risk losing those changes if you do not force EPF Composer to refresh |
| its memory cache. When you update files from your version control |
| system, those files are being changed outside of EPF Composer.</p> |
| |
| <p><b>Rule: Whenever you update files from your version control system,</b> |
| y<b>ou MUST refresh EPF Composer's memory cache.</b></p> |
| |
| <p>You can refresh the memory cache by either:</p> |
| <ul> |
| <li>Shutting down EPF Composer and starting it again</li> |
| <li>Reopening your method library in EPF Composer (File > Open > |
| Method Library)</li> |
| </ul> |
| |
| <p>Here is a very common scenario that illustrates this problem.</p> |
| <ol> |
| <li>You start EPF Composer</li> |
| <li>You realize that you want to make a change that will affect the <code>plugin.xmi</code> |
| file</li> |
| <li>You go to your version control system and discover that you do not |
| have the latest version of <code>plugin.xmi</code> because another |
| team member has updated it.</li> |
| <li>You update <code>plugin.xmi</code> from the library and check it |
| out.</li> |
| <li>You go back to EPF Composer and make your change. <i>(Notice that |
| since you left EPF Composer open, it has the old <code>plugin.xmi</code> |
| in its memory cache.)</i></li> |
| <li>You check back in all of the files involved in your change, |
| including <code>plugin.xmi</code>.</li> |
| </ol> |
| |
| <p><b>PROBLEM:</b> Since you did NOT refresh EPF Composer's memory cache |
| after you updated and checked out <code>plugin.xmi</code>, the <code>plugin.xmi</code> |
| you have just checked into your version control system has lost the |
| changes made by your teammate.</p> |
| |
| <p>If you encounter this problem, the safest way to recover is to back |
| out your changes and redo them with the proper version of <code>plugin.xmi</code> |
| in EPF Composer's memory cache.</p> |
| |
| <p>NOTE: When you check out the files you need to modify, if you are |
| uncertain whether any file changed, then it is best to be safe: shut |
| down and restart EPF Composer before making your changes.</p> |
| |
| |
| <h1 class="content"><a name="control">5. Make Both Applications Think |
| They Are in Control</a></h1> |
| |
| <p>Both EPF Composer and your version control system need to be in |
| control of the names of files and directories. Some changes that you |
| make to the Method Library in EPF Composer will cause files to be |
| renamed, deleted or moved, but your version control system will know |
| nothing about these changes. You need to manually simulate the same |
| change for your version control system. Changes that affect the names of |
| files or directories, or that delete files or directories, must be |
| performed in both EPF Composer and in your version control system.</p> |
| <p>The following instructions describe how to rename a method element |
| using IBM Rational Clear Case. The procedure for other version control |
| systems is similar. The procedure to rename a directory or to delete a |
| file or directory is also similar. When new files are created, don't |
| forget to put them under source code control, as usual.</p> |
| |
| <h2 class="content"><a name="rename">5.1 Rename a Method Element</a></h2> |
| |
| <p>Renaming a method element not only changes the name of the element's |
| file, but also causes a change to <code>plugin.xmi</code>.</p> |
| |
| <h3 class="content"><a name="cc2">5.1.1 For ClearCase Users</a></h3> |
| <ol> |
| <li>Update your library to make sure you have the latest files.</li> |
| <li>Use IBM Rational ClearCase to check out the content file and the <code>plugin.xmi</code> |
| file. Put in a comment to say that you are doing a rename, in case |
| someone needs to back out this change.</li> |
| <li>Open EPF Composer and rename the method element. For example, |
| rename the content element <code>oldname</code> to <code>newname</code>. |
| EPF Composer actually renames the file <code>oldname.xmi</code> to <code>newname.xmi</code>.</li> |
| </ol> |
| |
| <p>At this point, IBM Rational ClearCase thinks you have <code>oldname.xmi</code> |
| checked out, but that file is gone now. We need to do a rename in IBM |
| Rational ClearCase, as well. We cannot do that while the file is checked |
| out.</p> |
| <ol> |
| <li>Using your file system, rename <code>newname.xmi</code> back to <code>oldname.xmi</code>.</li> |
| <li>Check <code>oldname.xmi</code> back in.</li> |
| <li>Use IBM Rational ClearCase to rename <code>oldname.xmi</code> to <code>newname.xmi</code>. |
| At this point, the library is corrupt, because the old <code>plugin.xmi</code> |
| is still referring to <code>oldname.xmi</code>.</li> |
| <li>Check <code>plugin.xmi</code> back in. The library is no longer |
| corrupt.</li> |
| <li>The rename in IBM Rational ClearCase also causes a change to the |
| version controlled DIRECTORY that contains the files, as well as a |
| change to the file itself. Do a “find checkouts” on the library to |
| make sure that the directory got checked in correctly. If the |
| directory is still checked out, check it in. If it requires merging, |
| just accept the automatic merge.</li> |
| </ol> |
| |
| |
| <h1 class="content"><a name="consistency">6. Maintain Consistency of |
| Method Library References</a></h1> |
| |
| <p>Several files (<code>library.xmi</code>, <code>plugin.xmi</code>, and |
| <code>model.xmi</code>) contain cross-reference information about other |
| files. It is important to check in your files in a manner that preserves |
| the validity of these cross-references.</p> |
| |
| <h2 class="content"><a name="cipl">6.1 Checking in <code>plugin.xmi</code> |
| or <code>library.xmi</code></a></h2> |
| |
| <p>The order in which you check in <code>plugin.xmi</code> and <code>library.xmi</code> |
| depends upon the type of changes you were making. Since <code>plugin.xmi</code> |
| and <code>library.xmi</code> contain references to other files or |
| plug-ins (<code>library.xmi</code>), you will encounter errors opening |
| EPF Composer if the files referenced by <code>plugin.xmi</code> or <code>library.xmi</code> |
| are not present. To prevent this from occurring, you need to be careful |
| about timing your check-ins of these two files.</p> |
| |
| <ul> |
| <li><b>New files created:</b> In this case, you should check in <code>plugin.xmi</code> |
| and <code>library.xmi</code> after you have added the new content to |
| source control.</li> |
| <li><b>Files deleted:</b> If you delete method content or a plug-in, |
| then you should check in <code>plugin.xmi</code> and <code>library.xmi</code> |
| first, prior to actually deleting the files from your version control |
| system.</li> |
| <li><b>Other changes</b> <b>that also affect <code>plugin.xmi</code> |
| or <code>library.xmi</code>: </b>It is probably best to check <code>plugin.xmi</code> |
| or <code>library.xmi</code> into your version control system last, |
| after checking in modifications made to the other files.</li> |
| </ul> |
| |
| <h2 class="content"><a name="cim">6.2 Checking in <code>model.xmi</code></a></h2> |
| |
| <p>Similarly, <code>model.xmi</code> should be checked in first, if you |
| delete elements from your processes, and last if you are adding new |
| elements to your processes. See the previous section on checking in <code>plugin.xmi</code> |
| or <code>library.xmi</code> for details.</p> |
| |
| |
| <h1 class="content"><a name="conflict">7. Some Ways to Minimize Shared |
| File Conflicts</a></h1> |
| |
| <p>It is recommended that you control access to the shared files (<code>library.xmi</code> |
| and <code>plugin.xmi</code>) in order to minimize conflicts between |
| these files that may be shared by many. You can do this by:</p> |
| <ul> |
| <li>Establishing the overall content of the method library first |
| (e.g., what plug-ins and what configurations will it include). Make |
| these changes in EPF Composer to prime the <code>library.xmi</code> |
| file. If you will have many individuals working on your library, you |
| might want to develop your content in many separate plug-ins, so that |
| you minimize the number of persons working on each plug-in. This will |
| reduce the number of shared files that you need to contend with.</li> |
| <li>Establishing the method architecture up front (e.g., what method |
| elements the plug-in will contain, their names, presentation names, |
| brief descriptions, and relationships). Make these changes in EPF |
| Composer to prime the <code>plugin.xmi</code> file.</li> |
| <li>Making many small, incremental changes, checking each change into |
| your source library, rather than making many at one time before |
| checking in the changes.</li> |
| <li>Checking out the files you need to change (see <a href="#a">Appendix |
| A: Based on Your Actions, What Files Change?</a>), making your change, |
| and then checking the files back in right away. (<b>Hint:</b> If you |
| are not sure what files you need to check out, you can let EPF |
| Composer tell you. With the files still read only, try to make your |
| change in EPF Composer. EPF Composer will tell you what files need to |
| be writable.)</li> |
| </ul> |
| |
| <p><b>Caution:</b> Remember, if you need to check out <code>library.xmi</code> |
| or <code>plugin.xmi</code> to make your change, be sure you refresh EPF |
| Composer's memory cache if you did not already have the latest version |
| of one of these files. (See <i>Extremely Important: Refresh EPF |
| Composer's Memory Cache</i>)</p> |
| |
| |
| <h1 class="content"><a name="cc3">8. For ClearCase Users</a></h1> |
| |
| <p>If you are using IBM Rational ClearCase, remember that you must |
| update your files before you check them out. This order is important |
| because ClearCase does not update any files that you have checked out. |
| So, if someone has made a change to a file after you obtained your |
| snapshot of that file and you check out the file before updating it from |
| your source library, then you will be making your changes to an old |
| version of the file. ClearCase will not allow you to check your changed |
| file back in. You will need to obtain a new version of the file and make |
| your changes all over again.</p> |
| |
| |
| <h1 class="appendix"><a name="a">Appendix A: Based on Your Actions, What Files |
| Change?</a></h1> |
| |
| <p>The following table shows examples of actions that may result in more |
| than one file being updated or that could result in a change that |
| requires special attention in your version control system, such as</p> |
| <ul> |
| <li>A filename change</li> |
| <li>A filed moved from one directory to another</li> |
| <li>A file deleted</li> |
| <li>A file created</li> |
| </ul> |
| |
| <p><i>Note: This table shows common actions, it may not cover every |
| action that needs special attention.</i></p> |
| <table border=1 cellspacing=0 cellpadding=2> |
| <thead> |
| <tr> |
| <th>Action</th> |
| <th>What Changed</th> |
| <th>Comments</th> |
| </tr> |
| </thead> |
| <tr> |
| <td> |
| <p>Change the name of a method content element (task, role, work |
| product, guidance, custom category, or standard category)</p> |
| <p>Note: This includes contributing, extending, or replacing content |
| elements.</p> |
| </td> |
| <td> |
| <ul> |
| <li>The <code><method content>.xmi</code> file name is |
| changed <code>plugin.xmi</code> is changed</li> |
| </ul> |
| </td> |
| <td>Name refers to the name field for the element in the EPF |
| Composer editor. Be sure to rename the file in your version control |
| system.</td> |
| </tr> |
| <tr> |
| <td>Change the name of a process element (capability pattern (CP) or |
| delivery process (DP))</td> |
| <td> |
| <ul> |
| <li>The directory name for your CP/DP is changed to match the new |
| name.</li> |
| <li><code>plugin.xmi</code> is changed to reference the new |
| directory name.</li> |
| </ul> |
| </td> |
| <td>In your version control system, be sure to rename the directory |
| before you check-in the updated <code>plugin.xmi</code>.</td> |
| </tr> |
| <tr> |
| <td>Change the Presentation Name of a method element or process</td> |
| <td> |
| <ul> |
| <li><code>plugin.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>Move a content element to another plug-in</td> |
| <td> |
| <ul> |
| <li>File moves from one directory to another</li> |
| <li><code>plugin.xmi</code> for both plug-ins changes</li> |
| </ul> |
| </td> |
| <td>In your version control system, be sure to move the file before |
| you check-in the updated <code>plugin.xmi</code> files.</td> |
| </tr> |
| <tr> |
| <td>Create a new method content element (task, role, work product, |
| guidance, custom categories, or standard category)</td> |
| <td> |
| <ul> |
| <li>A new <code><method content>.xmi</code> file is created</li> |
| <li><code>plugin.xmi</code> is changed</li> |
| </ul> |
| </td> |
| <td>Need to place the new file under source code control. Be sure to |
| place the new file under source code control BEFORE checking in <code>plugin.xmi</code>.</td> |
| </tr> |
| <tr> |
| <td>Delete a method content element (task, role, work product, |
| guidance, custom categories, or standard category)</td> |
| <td> |
| <ul> |
| <li>The <code><method content>.xmi</code> file is deleted</li> |
| <li><code>plugin.xmi</code> is changed</li> |
| </ul> |
| </td> |
| <td>Be sure to delete the file in your version control system.</td> |
| </tr> |
| <tr> |
| <td>Refine the descriptive text for a method element (all fields |
| except the name, presentation name, or brief description)</td> |
| <td> |
| <ul> |
| <li>The <code><method content>.xmi</code> file is updated</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>Create a new plug-in</td> |
| <td> |
| <ul> |
| <li>New directory is created</li> |
| <li>New <code>plugin.xmi</code> is created in the new plug-in |
| directory</li> |
| <li><code>library.xmi</code> is changed</li> |
| </ul> |
| </td> |
| <td> |
| <p>Need to place new directory and new <code>plugin.xmi</code> file |
| under source code control. Be sure to check in the new <code>plugin.xmi</code> |
| BEFORE checking in <code>library.xmi</code>.</p> |
| <p>Note: You might want to develop your content in many separate |
| plug-ins, to minimize the number of persons working on each plug-in.</p> |
| </td> |
| </tr> |
| <tr> |
| <td>Delete a plug-in</td> |
| <td> |
| <ul> |
| <li>The entire directory for the plug-in is deleted</li> |
| <li><code>library.xmi</code> is changed</li> |
| </ul> |
| </td> |
| <td>Be sure to perform the corresponding deletes in your version |
| control system.</td> |
| </tr> |
| <tr> |
| <td>Rename a plug-in</td> |
| <td> |
| <ul> |
| <li>The name of the plug-in's directory is changed</li> |
| <li><code>library.xmi</code> is changed</li> |
| </ul> |
| </td> |
| <td>Be sure to rename the directory in your version control system. |
| </td> |
| </tr> |
| <tr> |
| <td>Create a new capability pattern (CP) or delivery process (DP)</td> |
| <td> |
| <ul> |
| <li><code>library.xmi</code> is modified</li> |
| <li><code>plugin.xmi</code> is modified</li> |
| <li>New directory and new <code>model.xmi</code> and <code>content.xmi</code> |
| files are created for the new CP/DP</li> |
| </ul> |
| </td> |
| <td> |
| <p><code>library.xmi</code> is modified to update the configuration |
| to include the new CP or DP. <code>Plugin.xmi</code> is updated to |
| include a reference to the new CP or DP. Be sure to place the new |
| file(s) under source code control BEFORE checking in <code>library.xmi</code>.</p> |
| <p>Note: It is advisable to double-check that your new process has |
| been selected in your configuration. If it is not, you will not see |
| it in the Configuration View.</p> |
| </td> |
| </tr> |
| <tr> |
| <td>Delete a process (CP or DP)</td> |
| <td> |
| <ul> |
| <li><code>library.xmi</code> is modified</li> |
| <li><code>plugin.xmi</code> is modified</li> |
| <li>The directory for the process and its contents are deleted</li> |
| </ul> |
| </td> |
| <td>Be sure to delete the directory and its contents in your version |
| control system.</td> |
| </tr> |
| <tr> |
| <td>Rename a process (CP or DP)</td> |
| <td> |
| <ul> |
| <li><code>library.xmi</code> is modified</li> |
| <li><code>plugin.xmi</code> is modified</li> |
| <li>The directory for the process is renamed</li> |
| </ul> |
| </td> |
| <td>Be sure to rename the directory in your version control system. |
| </td> |
| </tr> |
| <tr> |
| <td>Create, rename, or delete content package or process package</td> |
| <td> |
| <ul> |
| <li><code>plugin.xmi</code> is modified |
| </ul> |
| Note: Content and process packages do not result in new directories |
| being created in the file structure.</td> |
| <td>When you create a new package, you may want to select it in your |
| configuration. This will cause <code>library.xmi</code> to be |
| modified.</td> |
| </tr> |
| <tr> |
| <td>Create a new custom category</td> |
| <td> |
| <ul> |
| <li><code>plugin.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td>You may notice a <code>\customcategories</code> directory in |
| some of the plug-ins shipped with EPF Composer. Early versions of |
| EPF Composer created a directory for each custom category.</td> |
| </tr> |
| <tr> |
| <td>Update the brief description for a method content element (task, |
| role, work product, guidance, custom categories, standard category, |
| or process (CP or DP))</td> |
| <td> |
| <ul> |
| <li><code>plugin.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>Assign a relationship to an element, such as adding guidance, |
| tool mentors, input or output work product, responsible role, |
| performing role, etc.</td> |
| <td> |
| <ul> |
| <li><code>plugin.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>Categorize an element by assigning it to a domain, work product |
| kind, role set, or discipline)</td> |
| <td> |
| <ul> |
| <li><code>plugin.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>Assigning variability to an element by making it a contributor, |
| extension, or replacement for another element</td> |
| <td> |
| <ul> |
| <li><code>plugin.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>Assigning a shape or node icon</td> |
| <td> |
| <ul> |
| <li><code>plugin.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>Add or change descriptive text for a process (not the brief |
| description)</td> |
| <td> |
| <ul> |
| <li><code>content.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>Update the brief description an activity in a process (CP or DP) |
| </td> |
| <td> |
| <ul> |
| <li><code>model.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>Modify or create a diagram for a process</td> |
| <td> |
| <ul> |
| <li><code>model.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>Update the name or presentation name of an activity</td> |
| <td> |
| <ul> |
| <li><code>model.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>Update the attributes for a process activity (ongoing, |
| repeatable, etc)</td> |
| <td> |
| <ul> |
| <li><code>model.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>Set or update the entry or exit state of a work product</td> |
| <td> |
| <ul> |
| <li><code>model.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>Set or update activity relationships (predecessors, extend, |
| copy)</td> |
| <td> |
| <ul> |
| <li><code>model.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>Create, delete, or modify a configuration</td> |
| <td> |
| <ul> |
| <li><code>library.xmi</code> is modified</li> |
| </ul> |
| </td> |
| <td> </td> |
| </tr> |
| </table> |
| |
| |
| <h1 class="appendix"><a name="b">Appendix B: For each EPF Composer File, What |
| Changes Affect the File?</a></h1> |
| |
| <p>This section describes what changes affect what EPF Composer file.</p> |
| |
| <p>The following table lists the <code>.xmi</code> files created and |
| managed by EPF Composer. For each file, we describe what types of |
| changes affect those files:</p> |
| |
| <table border=1 cellspacing=0 cellpadding=2> |
| <thead> |
| <tr> |
| <th>EPF Composer File</th> |
| <th>Changes that Affect the File</th> |
| </tr> |
| </thead> |
| <tr> |
| <td><code>library.xmi</code></td> |
| <td> |
| <ul> |
| <li>Creating/deleting/renaming a plug-in</li> |
| <li>Creating/deleting/renaming a process (a capability pattern or |
| a delivery process)</li> |
| <li>Changing a configuration</li> |
| </ul> |
| </td> |
| </tr> |
| <tr> |
| <td><code>plugin.xmi</code> |
| <div class="note">(one for each plug-in)</div> |
| </td> |
| <td> |
| <ul> |
| <li>Creating/deleting method elements (method content or |
| processes)</li> |
| <li>Creating/refining method element brief descriptions (method |
| content or processes)</li> |
| <li>Creating/refining method element names (name or presentation |
| name)</li> |
| <li>Creating/refining method content variability (contribute, |
| extend, replace)</li> |
| <li>Creating/refining relationships (guidance, inputs work |
| products, output work products, roles)</li> |
| <li>Creating/refining categorizations (domain, work product kind, |
| role set, discipline)</li> |
| <li>Creating/refining method content categories (custom or |
| standard)</li> |
| <li>Creating/refining method packages (method content or process |
| packages)</li> |
| <li>Assigning a shape or node icon</li> |
| <li>A new <code>plugin.xmi</code> file is created when a new |
| plug-in is created</li> |
| </ul> |
| </td> |
| </tr> |
| <tr> |
| <td><code><method content name>.xmi</code> |
| <div class="note">(one for each method content element)</div> |
| </td> |
| <td> |
| <ul> |
| <li>Refining the descriptive text for the method content element |
| (all fields except the name, presentation name and brief |
| description).</li> |
| <li>Changing the name of a method content element will cause the |
| name of this file to change.</li> |
| </ul> |
| </td> |
| </tr> |
| <tr> |
| <td><code><process name>/model.xmi</code> |
| <div class="note">(one for each process)</div> |
| </td> |
| <td> |
| <ul> |
| <li>Creating/refining activities</li> |
| <li>Creating/refining activity brief descriptions</li> |
| <li>Creating/refining activity names (name and presentation name)</li> |
| <li>Creating/refining activity relationships (predecessor, extend, |
| copy)</li> |
| <li>Creating/refining process diagrams</li> |
| <li>Refining the activity attributes (found on the General |
| properties tab), such as repeatable, ongoing, etc. or predecessor |
| relationships</li> |
| <li>Creating/refining the entry or exit state of a work product</li> |
| </ul> |
| </td> |
| </tr> |
| <tr> |
| <td><process name>/<code>content.xmi</code> |
| <div class="note">(one for each process)</div> |
| </td> |
| <td> |
| <ul> |
| <li>Refining textual content of method descriptors (tasks, roles, |
| work products). This includes all of the descriptive text, except |
| the presentation names and brief descriptions</li> |
| </ul> |
| </td> |
| </tr> |
| </table> |
| |
| <p>Made available under the EPL v1.0.</p> |
| |
| </body> |
| </html> |