1. Overview of EPF Composer Files

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 .xmi file, see Appendix A: Based on Your Actions, What Files Change? or Appendix B: For each EPF Composer File, What Changes Affect the File?.
1.1 library.xmi

There is one library.xmi 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.
1.2 plugin.xmi

There is one plugin.xmi 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.
1.3 <method content element>.xmi

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.)
1.4 model.xmi

There is one model.xmi 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 plugin.xmi.
1.5 content.xmi

There is one content.xmi 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.
2. Locate your Library and Prime It Appropriately

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.

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.
2.1 You Want to Extend OpenUP/Basic

If you want to use the Method Library that is provided with EPF Composer, you will need all of the files in the \library 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.

We suggest that you make a copy of the \library directory and place it where you want your controlled source. Also place the library.xmi file (\library\library.xmi) under source code control, since you will need to modify this file.

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 library.xmi. 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.

When you start EPF Composer, you just need to point it to the directory where your controlled library.xmi file exists.

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.
2.2 You Want to Create Your own Library

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).

2.4 A Note about the .project File

When you start EPF Composer, it will create a .project file in the directory where your controlled library.xmi file exists. You should not place this .project file under version control since the tool will create one on each user's workspace.
2.5 Put all Files being Developed under Version Control

As files and directories are added to your method library, place them under version control.
3. Ensure the Appropriate Files Are Writable

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 Appendix A: Based on Your Actions, What Files Change? 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.
3.1 Method 1 (Recommended): Work directly in your controlled source library

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.

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 library.xmi file.

Pros: 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.

Cons: 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.
3.2 Method 2: Work in a copy of your controlled source library

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 (http://www.scootersoftware.com/). Copy the files that changed over to your source control library and check these files into your version control system.

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 library.xmi file.

Pros: 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.

Cons: 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 library.xmi or plugin.xmi.

Caution: 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, you must be very careful 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.
4. Extremely Important: Refresh EPF Composer's Memory Cache

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.

Rule: Whenever you update files from your version control system, you MUST refresh EPF Composer's memory cache.

You can refresh the memory cache by either:

    * Shutting down EPF Composer and starting it again
    * Reopening your method library in EPF Composer (File > Open > Method Library)

Here is a very common scenario that illustrates this problem.

   1. You start EPF Composer
   2. You realize that you want to make a change that will affect the plugin.xmi file
   3. You go to your version control system and discover that you do not have the latest version of plugin.xmi because another team member has updated it.
   4. You update plugin.xmi from the library and check it out.
   5. You go back to EPF Composer and make your change. (Notice that since you left EPF Composer open, it has the old plugin.xmi in its memory cache.)
   6. You check back in all of the files involved in your change, including plugin.xmi.

PROBLEM: Since you did NOT refresh EPF Composer's memory cache after you updated and checked out plugin.xmi, the plugin.xmi you have just checked into your version control system has lost the changes made by your teammate.

If you encounter this problem, the safest way to recover is to back out your changes and redo them with the proper version of plugin.xmi in EPF Composer's memory cache.

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.
5. Make Both Applications Think They Are in Control

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.

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.
5.1 Rename a Method Element

Renaming a method element not only changes the name of the element's file, but also causes a change to plugin.xmi.

6. Maintain Consistency of Method Library References

Several files (library.xmi, plugin.xmi, and model.xmi) 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.
6.1 Checking in plugin.xmi or library.xmi

The order in which you check in plugin.xmi and library.xmi depends upon the type of changes you were making. Since plugin.xmi and library.xmi contain references to other files or plug-ins (library.xmi), you will encounter errors opening EPF Composer if the files referenced by plugin.xmi or library.xmi are not present. To prevent this from occurring, you need to be careful about timing your check-ins of these two files.

    * New files created: In this case, you should check in plugin.xmi and library.xmi after you have added the new content to source control.
    * Files deleted: If you delete method content or a plug-in, then you should check in plugin.xmi and library.xmi first, prior to actually deleting the files from your version control system.
    * Other changes that also affect plugin.xmi or library.xmi: It is probably best to check plugin.xmi or library.xmi into your version control system last, after checking in modifications made to the other files.

6.2 Checking in model.xmi

Similarly, model.xmi 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 plugin.xmi or library.xmi for details.
7. Some Ways to Minimize Shared File Conflicts

It is recommended that you control access to the shared files (library.xmi and plugin.xmi) in order to minimize conflicts between these files that may be shared by many. You can do this by:

    * 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 library.xmi 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.
    * 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 plugin.xmi file.
    * Making many small, incremental changes, checking each change into your source library, rather than making many at one time before checking in the changes.
    * Checking out the files you need to change (see Appendix A: Based on Your Actions, What Files Change?), making your change, and then checking the files back in right away. (Hint: 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.)

Caution: Remember, if you need to check out library.xmi or plugin.xmi 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 Extremely Important: Refresh EPF Composer's Memory Cache)

• Using EPF Composer with a Version Control System