Using CVS with Portlet Factory
CVS can easily be used to collaborate and share work within a team of developers working on a common WebSphere Portlet Factory project. However, there are some considerations that should be kept in mind when configuring the WebSphere Portlet Factory workspace for use with CVS.
Following is a discussion of the recommended method to setup a team collaboration environment for sharing work within a WebSphere Portlet Factory project.
Start Early
First, it is highly recommended to setup and configure a CVS repository early in the project; the sooner, the better. This will prevent issues with conflicting versions of project files later in the development process.
Individual Configuration
Due to the manner in which the WebSphere Portlet Factory Designer works, it is advised that each developer on the project create a new WebSphere Portlet Factory project in their workspace rather than share the entire project or workspace. This allows each developer to create the project with the correct specification of settings for their own WebSphere Portal server test environment. For example, each developer may have different installation paths that have been used for their WebSphere Portal server, and each developer very likely has different admin user IDs and/or passwords used for their WebSphere Portal server. For these reasons, it is imperative that each developer setup and configure their own WebSphere Portlet Factory project through the New wizard in Eclipse.
Decide What to Share
You will need to decide how much of the WebSphere Portlet Factory project needs to be shared among the team. Following is a discussion of the ability to share the various types of files found in a WebSphere Portlet Factory project. In regards to collaborating on a WebSphere Portlet Factory project, there are 3 classifications of files in the project.
These file classes are:
- files that need to be shared
- files that should not be shared
- files that can be shared
It is recommended that only the first class of files be shared in CVS.
files that need to be shared
The first class of files, files that need to be shared, is obvious. These files are the entire reason for setting up a source code repository and version control system in the first place. Any files, including model files, profile sets, html templates, images, style sheets, etc. that are created by a developer should be shared among the team through CVS. Some of these files, such as a WebSphere Portlet Factory model file are created directly by a developer. Other types of these files are created indirectly by WebSphere Portlet Factory Designer, for example a Builder Definition file (.bdef) created by the Builder Skeleton builder. Generally speaking, any files created in a WebSphere Portlet Factory project after the initial creation of the project need to be shared in CVS.
files that should not be shared
The second class of files, files that should not be shared, includes various files that are created and used internally by WebSphere Portlet Factory. These files all include very specific data about the individual workspace in which they were created. These files contain information such as the local file system path to the workspace, the local file system path to the WebSphere portal installation, the userids and (encrypted) passwords for the WebSphere Portal automatic deployment configuration, etc. Unless every developer on the team is using an identically configured system where these paths, userids and passwords are identical, then these files should not be shared. If these files are shared, you run the risk of corrupting the workspaces of other team members. The files in this class should not be directly edited by a developer. An example of a file in this class is the .bowstreet file in the root of the Eclipse project.
files that can be shared
The third class of files, files that can be shared, includes various files which are part of the standard WebSphere Portlet Factory project. This set would include files such as standard .jar files, models, profile sets, html templates, style sheets, images, etc. that are packaged as part of WebSphere Portlet Factory. The files in this class should not be directly edited by a developer. Files in this class can be shared in CVS, but there is really no need to do so.
Setup CVS to Ignore Resources
Once the set of desired files to be shared has been identified, CVS should be configured to ignore the rest of the files in the workspace. This should be done through the creation of a set of .cvsignore files. These .cvsignore files themselves should be committed to CVS.
Synchronizing Workspaces
Once the desired set of files from the first workspace has been committed to CVS and the set of .cvsignore files committed to CVS, then other developers on the team can begin to synchronize their workspaces with CVS. Additional workspaces should be synchronized with CVS by first performing an Update operation in order to retrieve all of the existing project files and .cvsignore files from CVS. Following the Update operation on the initial synchronization, the Synchronize view in Eclipse will show only two classes of files. Those files unique to the workspace that aren't already in CVS, and those files within the workspace which conflict with a file in CVS. For each file in the workspace that is not already in CVS, a decision should be made wether to add that file to a .cvsignore list or to commit it to CVS. For each file that is in conflict with CVS, a determination must be made as to which version of the file is authoratative. This is not always an easy task. (Remember the section above about starting early?)
Quick Way to CVS
A utility has been created to ease the creation of the set of .cvsignore files for a WebSphere Portlet Factory project. Following is a discussion of how to use this utility and provide a quick way to get your team working with a CVS repository.
- Create a new WebSphere Portlet Factory project; even if you have already created a WebSphere Portlte Factory project and have already been developing in it. (Use the New->WebSphere Portlet Factory Project wizard in Eclipse.)
- Execute the CVSIgnoreGenerator utility against the new project. (The CVSIgnoreGenerator utility follows the recommended approach and generates .cvsignore files to ignore all files in the WebSphere Portlet Factory project except those developer created artifacts that need to be shared.)
- Copy all .cvsignore files created by the CVSIgnoreGenerator utility into the project.
- Right click on the project in Eclipse and select the Refresh operation.
- Share this new project into CVS. (Use the Team->Share Project wizard from the project's local menu.)
The only files that the wizard should identify to be committed to CVS should be the set of .cvsignore files.
Commit the .cvsignore files to CVS.
- Use this project to begin your development work. (Any new files added to the project should be available to be committed to CVS.)
OR
Synchronize your existing project with CVS. (Use the Team->Share Project wizard from the project's local menu.)
Do not commit any files until you have first successfully completed an Update operation with CVS to retrieve the set of .cvsignore files.
The only files that the wizard should identify as eligible to be committed to CVS are those which have been created in the project by the developer.
The CVSIgnoreGenerator Utility
CVSIgnoreGenerator is a utility to generate .cvsignore files for WebSphere Portlet Factory projects.
The syntax for the utility is as follows:
java com.ibm.wpf.CVSIgnoreGenerator [destination_path]
where:
- source_path is the location of a WebSphere Portlet Factory project
- destination_path is the optional location for the output of the utility
If destination_path is omitted, the utility writes the generated .cvsignore files to the source_path.
If destination_path ends with .zip, a .zip file is created to contain the generated .cvsignore files, otherwise, destination_path is treated as a directory where the .cvsignore files will be written to.
This utility should be run on a new WebSphere Portlet Factory project. If user created artifacts already exist in the project, they will be added to the generated .cvsignore files and subsequently excluded from CVS.
This utility generates .cvsignore files which will ignore all files in the specified WebSphere Portlet Factory project on a file by file basis. This allows user created artifacts to be added to the project and synchronized into a CVS repository without the need to alter or maintain the .cvsignore files.
The only exception to the above is that this utility generates a directory wide exclusion for the WEB-INF/classes, WEB-INF/factory/bak, WEB-INF/factory/generated, and WEB-INF/work/classes directories (and all of their children).
The recommended usage of this utility is as follows:
- execute this utility to generate a set of .cvsignore files for a WebSphere Portlet Factory project
- commit all generated .cvsignore files to CVS; do NOT commit anything other than the .cvsignore files
- synchronize each user's workspace with CVS and perform an Update operation to retrieve the .cvsignore files; do NOT commit anything at this stage until all .cvsignore files have been updated from the repository
- re-execute the synchronize operation on each user's workspace and commit any user created artifacts to CVS
The CVSIgnoreGenerator utility can be downloaded here:
cvsignoreutil.zip