Using EPF with a Version Control System.htm

<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&reg;
Rational&reg; ClearCase&reg; 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>&lt;method content element&gt;.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>&lt;method content
element&gt;.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
(&lt;method content element&gt;) 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 &gt; New &gt; 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&reg; 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 &gt; Open &gt;
  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>&lt;method content&gt;.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>&nbsp;</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>&lt;method content&gt;.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>&lt;method content&gt;.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>&lt;method content&gt;.xmi</code> file is updated</li>
    </ul>
    </td>
    <td>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</td>
  </tr>
  <tr>
    <td>Assigning a shape or node icon</td>
    <td>
    <ul>
      <li><code>plugin.xmi</code> is modified</li>
    </ul>
    </td>
    <td>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</td>
  </tr>
  <tr>
    <td>Create, delete, or modify a configuration</td>
    <td>
    <ul>
      <li><code>library.xmi</code> is modified</li>
    </ul>
    </td>
    <td>&nbsp;</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>&lt;method content name&gt;.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>&lt;process name&gt;/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>&lt;process name&gt;/<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>