Introduction

What is UCM4SVN

UCM4SVN is a layer built on open-source Subversion to provide additional Software Configuration Management features. These changes include tracking code development through the use of activities. Those familiar with the Rational Unified Process, which describes the life cycle of change management for IBM Rational's software development process, will recognise similarities with UCM4SVN. It gives software project managers and integrators the ownership and control over the higher level aspects of the environment such as component structures, creation of activities, assigning activities and most importantly the selective control over integration of activities and subsequent baselines.

The UCM4SVN architecture is designed to meet the following two main objectives:-

1. Create a thin Application Life Cycle layer to extend the functionality of Subversion and improve code management
2. Remain agnostic of Subversion interfaces, i.e. ensure that UCM4SVN works with all existing and future interfaces (CLI or GUI)

From the developers' perspective, they are assigned items of work (activities) for which code changes are made via any Subversion interface (command line, Tortoise, Eclipse, etc). Each activity is isolated on a self-contained subversion branch and the state of the activity is recorded via a simple set of 'state transitions'.

From the Integration Manager's perspective, the activity state can be managed and reported against and, when appropriate, integrated into a project integration branch.

Why UCM4SVN

The open source Subversion project has publicly stated that Application Life Cycle support is outside the scope of the project. The Subversion project provides the necessary options for the wider community to provide this functionality either commercially or as free-ware.

Whilst many consider Subversion 'out of the box' good enough for plain version control, there is a considerable and growing number of users who require a standardized, user-friendly process layer.

---

Terminology

What is a Component?

A component is generally considered to be a self-contained group of artefacts which can be considered as a reusable piece of architecture. For example, the Ford Motor company would consider the radio/cd player as a component to many different models of car because it is self-contained, could be easily exchanged for a different model radio/cd player and can also be used between different models of cars.

To make a component or to make alterations to a component will require effort. This effort is known as a Project.

The below table and diagram represents the logical and physical layout of the Subversion repository. A component in Subversion is a Subversion folder. Below this folder is a directory structure that helps separate projects and activities within projects as shown in the table below.

The example shows an engine component with two project integration branches and three activity branches. Activities are created for projects and are therefore merged back onto the project's integration branch. For example, activity Reduce Fuel Consumption was created for the 1 ltr engine project, and it was therefore merged back into the integration branch of that project. In the current release of UCM4SVN activities can only be merged onto the integration branch of the project for which they were created.

What is a Project?

A project is a collaborative enterprise (resources) that aims to achieve a particular result. It has a start date, a target end date and requires effort to change the state of the item being worked on.

A UCM4SVN project is the name given to a group of resources, namely a number of developers and components, which relate to a single development effort. The development effort is characterised by a number of activities performed by developers on components in the project.

For example, Ford Motor company decide to enhance the Ford Escort 'GL' by improving sound proofing and in parallel another project is running to enhance the Ford Fiesta 'L' version by improving the overall performance. The Escort 'L' and 'GL' versions of the car share many common components, however the 'GL' model might have either additional functionality or even better quality items than the 'L' model. The two projects will involve a total of four developers (Stephanie, Daniel, Kathryn and Gerald). The projects will start immediately and forecast to finish in 2 months time.

Alternative example - Projects contain resources (people and components)

The diagram below represents two developers working on the Engine Component. Daniel has been assigned the activity 'New spark plugs' whilst Stephanie has been assigned the activity 'New injectors' and also 'New spark plugs'. Assuming both activities need to modify the same file called 'Engine', UCM4SVN creates activity branches in order to isolate the work items.

According to the diagram, Stephanie has finished her work and 'delivered' the work into the integration branch. The activity 'New spark plugs' is still pending and has not yet been integrated (merged) onto the integration branch.

What is an Activity?

Activities are the collective development effort that move the project forward towards its goal. Individual activities tend to cover a relatively small effort, lasting somewhere between a couple of hours to a couple of days. Anything larger than a couple of days would most likely be broken down into smaller activities.

Activities are created by the role 'Project Manager' and assigned to the most appropriate member of the team. Activities can be worked on by more than one team member. For example, the Project Manager Gerald, who is also a developer, identifies a number of Activities relating to the iPod integration which require working effort. Each activity is created in UCM4SVN and assigned to the developers Stephanie, Daniel and Kathryn.

Integrating code, what does it mean?

UCM4SVN is designed to allow small 'activities' of work to be isolated and, when appropriate, merged into a project's main code line. This approach is generally considered to be a good approach as it offers the developer a degree of isolation and freedom to 'play and test' with the code knowing the work will not impact any other work items. From the team leaders and project managers perspective, they have the option to control what is added to the main line development and thus what features to include in the next baseline or release.

There are generally two different approaches to integrating code from activities into a common integration branch. The first approach is for the developer to 'Push' the changes into the integration branch, the alternative is for an experienced developer, the 'Integrator', to 'Pull' the changes from the individual activities onto the Integration branch. UCM4SVN allows for both options, the merits of each are discussed below.

Developers 'Push' integration

The developer who created the activity of work on an isolated branch is generally considered to be the most knowledgeable person to perform the integration and resolve any potential coding conflicts. The question regarding when or even if an activity should be integrated can be resolved via good communication with the stake holders. This can be achieved through regular meetings or via a change control process.

Integrator 'Pull' integration

Having an integration role within a development team has two main advantages:-

1. The stakeholders and the integrator can agree on what functionality to include at what point in time. This provides a centralised point for integrating and adding functionality.
2. The integrator can also perform code reviews prior to allowing code onto the critical integration path. This is especially relevant with new members to a development team or junior developers.

The disadvantage with the 'Pull' approach is the reliance on the integrator. In a busy development environment it might be too much work to keep up with the flow of changes.

UCM4SVN does not force either approach and actually encourages an open approach by leaving the project to decide what is right for them.

---

Workflow

How to use UCM4SVN

The diagram below represents a very high level usage digram for UCM4SVN. Once the components and projects definitions have been defined, Activities are created and assigned to developer(s). Once the Activity is complete, either the developer delivers the changes into the common integration point for the Project or the person assigned to the Integrator role selectively pulls the undelivered activities into the common integration point. The new common integration point would generally become the next baseline for new activities.

1. SVN Admin creates the subversion repository using standard SVN commands
2. UCM4SVN Admin creates the Project Admin role
3. UCM4SVN Project Admin creates the additional users and assigns roles to the users
4. UCM4SVN Project Admin creates the UCM4SVN components and projects
5. UCM4SVN Project Admin assigns the users to the newly created projects
6. UCM4SVN Project Admin creates and assigns activities to the users
7. UCM4SVN Project Developers list and accept activities to work on, once complete the developer has two choices;
   1. Deliver directly to the common integration branch
   2. Close the activity such that the UCM4SVN Integrator can PULL the activity to any number of integration branches
8. Process repeated back to step seven [6]

Menu Navigation

When you log in to UCM4SVN you are presented with a menu that reflects your access level. Administrators and project managers see the following menu shown at the top of the screen.

Other user roles see a reduced menu, for example developers only see a "To Do" and a "View Baselines" tab allowing them to work with activities that have been assigned to them. Note that the "View Baselines" tab is a restricted version of "Manage Baseline". Developers are allowed to view and browse baselines. However, they are not allowed to create new baselines or recommend baselines for a project.

You navigate to different functions by clicking on the option you require on the top menu bar (in the following also referred to as tabs).

At the top-right corner of the screen there are two links allowing you to log out from UCM4SVN (Logout) or to change your user profile using the My Account link.

Error Reporting

When performing actions with UCM4SVN, e.g. accepting activities or creating baselines, success is usually indicated through a green "tick" or "check" on a grey background. This is usually followed by a message indicating the name of the action and any additional information on the results of the action. For example, when creating a new user Mike, you might see the following output:-

If any errors occurred during the action, a red cross is displayed followed by the error messages. If applicable, UCM4SVN will also highlight errors in the form data provided by the user. The following example shows an unsuccessful operation.

The Search Box

Tabs presenting the user with a list view such as Edit User and Edit Component allow you to narrow down the number of items displayed by typing a search term in the text box at the top of the view and pressing the Search button. For example in the Edit Component view, if you enter the name or part of the name of a component and click search, all components with a component name that contains the text provided will be displayed.

You can reset the view either by clicking Edit Component again or clearing the contents of the text box and pressing Search again.

The search boxes for Edit Activity and Edit User provide the same functionality as Edit Component.

Roles

UCM4SVN supports four [4] different roles. A person can belong to one or more roles. The diagram below illustrates the actions available to each role. Each of these actions is explained in more detail in this document.

Database Admin

  This role is the super user for UCM4SVN and is used for creating the initial database structure.

Developer

  This role can only see and work on activities assigned to them.

Integrator

  The principle of the Integrator role is to mange activities which developers can or should not deliver.

Project Manager

  The project manager role manages project resources, i.e. people and components, and creates and assigns activities.

Functionality of each Role

• A newly copied blank database has two default accounts 'dbadmin' and 'admin' with the following assigned roles;

The user admin has access to all roles except dbadmin and is used to create the initial project users.

The user dbadmin has access to the back-end database. Please do not use this login unless you have been explicitly advised to do so by Clearvision Support.

Another related role is the Subversion administrator. Whilst this is not a UCM4SVN role, it is significant in the sense that a Subversion administrator must create a Subversion repository within which to store UCM4SVN data.

SVN Admin

   This is not a UCM4SVN role. This individual must create the initial SVN database

How to Use UCM4SVN

This section assumes that UCM4SVN has been installed and started according to the instructions in the UCM4SVN Administration Guide. It is also assumed that the SVN Administrator has created a Subversion repository for use by UCM4SVN.

Project Manager

Create new users and assign to roles

Ideally before a UCM4SVN project is created, the Project Manager will create the users and assign them to a suitable role.

Adding a new UCM4SVN user requires three [3] configuration options:-

User Name

   Free text field for the user's unique id. e.g. Sean_Connery or SConnery or Sir Sean Connery

Full Name

   Free text field for the user's full name. UCM4SVN will always display a combination of user name and full name when referring to users. For a user 'SConnery' with full name 'Sean Connery', UCM4SVN will display 'Sean Connery (SConnery)'.

Email

   Email address for the user. The email address is used to notify Developers of new activities assigned to them and Integrators of closed activities waiting to be integrated.

Password & Retype Password

   Free text field for the user's password.

Permission

   Select one or more roles which best describe the role performed by the user. See above table for the list of functions served by the role.

Optionally, you can also provide information on the user's Subversion user name and default workspace location. This information is used when checking out activities using the checkout scripts or Java Checkout GUI available from the To-do tab.

Svn user name

   Subversion user name to be used for the creation of checkout scripts and as the default user name in the Java Checkout Tool. If you are using the Java Checkout Tool to check out activities, the user name provided here is only used as the default and can be overridden in the GUI.

Svn default workspace dir

   You can specify the default location to be used for UCM4SVN to create Subversion workspaces for activities. Note that a new subdirectory is created for every activity you check out, so there is no need to change this setting to keep activities separate.

   If you mainly work on Windows platforms, please specify an absolute path including the drive letter, e.g. "C:\Documents and Settings\Daniel\My Documents\ucm4svn_workspace". If you mainly work on Linux platforms, please specify an absolute path to the location of your workspace.

   If you are using the Java Checkout Tool to check out activities, you can override the workspace location from the GUI.

If the JIRA and/or ClearQuest integration is enabled, users can also be imported from ClearQuest and JIRA. Click on the link underneath the User Name field, which will pull a list of available users (i.e. users that exist in JIRA/ClearQuest but do not exist in UCM4SVN yet).

You can then choose which users to import by selecting the user in the Import column and clicking the Add Users to UCM4SVN button.

Users added to UCM4SVN this way are automatically imported with the appropriate user type. The user type determines against which source a user's password is authenticated on login. A JIRA user's password will be checked against JIRA, a ClearQuest user's password is checked against ClearQuest, and the passwords of users manually created in UCM4SVN are checked against the UCM4SVN password specified when the user was created.

Note that you can change a user's User Type later with Edit User. This makes it possible, for example, to create a connection between a local UCM4SVN user with the same name as a JIRA user such that the next time the user logs in, their password is checked against JIRA. It also makes it possible to sever a user's link with JIRA or ClearQuest by setting the type to UCM4SVN. Please see section Edit User for details on how to change a user's type.

Edit Users and Re-assign Roles

Once a user has been created, the assigned roles for the user can be changed. It is important to note that items assigned to a user could become hidden e.g. Gerald is assigned the role Developer and has three [3] activities assigned. The Project Manager changes Gerald to become an Integrator and removes Gerald from the Developer role. The three activities will no longer be visible. The correct approach is to always reassign any dependencies, such as Activities, prior to changing a person's role.

Changing a UCM4SVN user role requires modifying the same fields as adding a new user. When you select the Edit User tab, a table is displayed showing a list of users and their current roles. To change a particular user's role, click on the user's name in the table, and complete the fields as per new user.

It is also possible to change a user's User Type. The main effect of changing a user's type is the change in the way the user's password is checked on login. For example, if a user's type is ClearQuest, UCM4SVN will contact ClearQuest in order to verify the user's password. This makes it possible to import users from ClearQuest or JIRA without having to enter a password in UCM4SVN as by default the user will be authenticated against the JIRA database.

Through the facility to change a user's type, you can create or sever the connection between a UCM4SVN user and JIRA or ClearQuest.

Note that is important to maintain a connection with JIRA/ClearQuest for users working on activities created in JIRA or ClearQuest. If the connection is severed and the password is changed in JIRA, the user will not be able to move JIRA or ClearQuest tickets to their next state and attach closing comments.

Also note that for environments where activities may come from both JIRA and ClearQuest, users are advised to maintain a connection with one of the systems through their user type and use the same password for both systems.

Create Components

A UCM4SVN component requires four [4] configuration options:-

Component Name

   The component name is used as part of the Subversion directory hierarchy, for this reason we recommended using a naming convention of less than 25 characters.

Description

   Free text field to describe the purpose and use of the component.

Container URL

   The container URL is the top level folder within a Subversion repository. The path provided must be a Subversion URL to a folder where the component can be created. Below this point UCM4SVN will create the headline subversion structure tags and branches.

If the repository is for the sole use of UCM4SVN (recommended), you can use the root of the repository itself (e.g. use http://www.my_repos.com/svn as the container URL). If you want to share the use of an existing repository with UCM4SVN, then we recommend creating a new top location for UCM4SVN components to seed from (e.g. http://www.my_repos.com/svn/ucm4svn_data ).

Note that this repository location, i.e. the path provided in the URL, must already exist. The component name will be automatically appended to the path.

The first time you create a component, the Container URL must be provided. UCM4SVN will remember this URL for the creation of future components. When more components are created, you can specify a new location for the new component, or you can choose one of the Container URL's used for other components. Note that UCM4SVN creates new subdirectories for each component at the Container URL location.

Create Project

A UCM4SVN project requires three [3] configuration options:-

Project Name

   Free text field to describe the purpose of the project e.g. Fiesta - Iteration One

Developers can deliver

   With this setting a Project Manager can control whether or not Developers are allowed to deliver their own activities or if activities are closed and then integrated by Integrators. Note that if Developers are allowed to deliver, they can still close tickets so that they can be integrated by Integrators. However, if the option is switched off, Developers are not allowed to deliver activities themselves. This setting can be changed later using Edit Project.

Activity Sources

   Select the source for activities. Provided !ClearQuest and JIRA integrations are enabled, you have a choice of "UCM4SVN", "!ClearQuest" and "JIRA". If allow_multiple_activity_sources=0 in the config file, you can only select one activity source. Otherwise, you can select multiple activity sources. NOTE: This setting cannot be changed once the project has been created.

Users

   Select from the total list of users who can work on this project. To select multiple users, hold down the Control key.

Component

   A project can span many components; select from the list one or more components. Only the contents of the selected component(s) will be available for this project. To select multiple components, hold down the Control key. As you select components, a new choice box will appear in the Initial Revisions section at the bottom of the screen, allowing you to select an initial baseline for each component and specify whether the component is writeable or read-only for this project. Please see below for more details on initial revisions.

JIRA Filter ID

   This is an optional field, which only needs to be completed if you are integrating with the JIRA change management system.

   Create a filter within JIRA to get the list of Issues that relate to a particular component, e.g. all outstanding bugs or features for the 'Porsche' component. Please make sure the filter is usable by the JIRA user specified in the config file. 

   In this field, please enter the JIRA Filter ID (a five-digit number), which you can find at the end of the URL after creating a new filter in JIRA. Alternatively when you view all filters in JIRA, hover over the filter and check the location in your browser. 

For example, the URL "http://jira.my-company.com:8080/secure/IssueNavigator.jspa?mode=hide&requestId=10010", indicates a JIRA Filter ID of "10010".

CQ Selector

   This is an optional field, which only needs to be completed if you are integrating with the ClearQuest change management system.

   The configuration of this field depends on the configuration of your installation. It is typically used to identify the project on ClearQuest queries.

   The UCM4SVN administrator can customise ClearQuest integration scripts to use the value of this field for different purposes. Please check with your UCM4SVN administrator for guidance on how to use this field. The default ClearQuest integration scripts use the value of this field as a filter on the Project field of the ClearQuest record.

Once you have selected a list of components, you get the opportunity to specify the Initial Revisions used for each component. As components are selected, a new entry is shown in the Initial Revisions sections at the bottom of the page. The Initial Revision is a baseline used to create the project branch for a new component. Any baseline from any project can be used as the initial revision for a component.

Note that when creating your first project, there are no baselines. You can simply proceed by pressing Create Project.

If you have selected a particular baseline for a component, you can also choose whether the component can be modified as part of this project or if you would like the component to be read-only. Read-only components are reference components that cannot be changed as part of activities. In Subversion terms, read-only components are exported (not checked out) via either a checkout script or a Java Checkout Tool. The file permissions for read-only components are changed to read-only.

Create Activity

A UCM4SVN activity requires the following configuration options:-

Project

   Select from the drop down list the project for which you would to create a new activity.

Activity Name

   Free text field to describe a short description of the small work item e.g. Add logo to steering wheel.

Description

   You can provide a verbose description regarding the activity, e.g. the nature of a problem or the details of a feature.

Assignments - Assign to

   Select a person to assign this activity to from a list of names. Note that assignments can be changed later using the Assign Activity or Re-assign Activity tabs.

If email notifications have been enabled in the configuration file, upon creation of the activity the assigned user(s) will be emailed to let them know they have an activity waiting for their acceptance.

An activity can also be created by importing an issue from JIRA or ClearQuest. This can be achieved from the New Activity page. Select the project the activity should be created under. If the JIRA/ClearQuest integration is turned on, a box should now appear allowing you to create an activity from a JIRA issue. Select the issues you want to create and then click Create Activity.

NOTE: Unless a UCM4SVN user exists whose user name matches the assigned user of the JIRA issue, the activity will not be assigned to any user. However, the issue will still be imported from Jira and left awaiting assignment. In this case, please use the Assign Activity tab to assign the activity to a user.

For activities imported from JIRA issues, if you have the issue workflow options enabled, then the issue can also be progressed through its various states in JIRA, assuming the user assigned in UCM4SVN has the correct permissions to adjust this issue in JIRA.

Similarly, for activities created from ClearQuest records, the user assigned in UCM4SVN requires adequate permissions in ClearQuest to append a closing comment to the record and progress the record to a new state.

Edit Project

The Project Manager role can edit an existing project to:

• alter the associated users
• change the associated components

Edit Component

The Project Manager role can edit an existing Component to:

• Change the description
• Change the recommended component baseline

Re-assign Activity

The Project Manager role can change the associated assignees for an existing activity.

Integrator

The role of the Integrator is to select from the list of 'Closed' development activities the activities which need integrating (merging) into the common integration branch. For the Integrator to see pending activities, developers must mark the activity as 'Closed'. Activities are merged to the project integration branch.

Users assigned the 'Integrators' role will have the menu options 'Integrate', 'Manage Baseline'.

Integrate - Merge Developers' Closed Activities

A UCM4SVN Integrate option requires two [2] configuration options:-

Project

   Select the Project for which to merge activities. 

Activities

   Select the appropriate activity by ticking the Merge box. Note that only Closed activities are shown. Any activities Delivered by developers have already been merged onto the project integration branch and therefore do not appear in this list.

Note: If an activity was created from a JIRA issue and the workflow options are enabled in the UCM4SVN configuration file, upon integration the activity will change its status in JIRA to 'Closed' and the closing comment left by the developer will also be transferred to JIRA.

You have the option to hide activities from the integration branch that you are not interested in. These activities will stay hidden until you press Show All Activities again.

If an activity requires changes or needs to be reviewed prior to a merge, Integrators have the option to rebase an activity with the latest changes on the project integration branch. You can rebase the activity by clicking on the icon in the Rebase column of the activity you would like to rebase.

You can also check out the activity by clicking on one of the checkout links or cutting and pasting the Subversion commands into a shell window. Please see the Developer section (subsection Checkout Activity) for details on how to check out activities using the links and tools provided.

If you would only like to have a look at the files that were changed for an activity, you can click on the activity name and then select the View Activity Changeset link at the top. Please see the Developer section, subsection View Activity Changeset for details on how to view the Subversion changeset for an activity.

Manage Baseline

The Manage Baseline tab is the main entry point for browsing, creating, qualifying and recommending baselines. You can view the activities that make up a baseline, create new baselines, browse baselines, checkout baselines (export to file system) and set the status of a baseline (qualify a baseline).

Create Baseline

Once a number of activities have been integrated and a stable point has been reached on the project's integration branch, the integrator can create a new baseline to capture the current state of the project integration branch.

You create a new baseline by selecting the project for which to create the baseline, entering a name in the Name field and pressing Make Baseline.

When a baseline is created, Subversion tags are created for each component in the Subversion repository to mark the existence of the baseline in the repository and make it possible to check out the baseline.

Once a baseline has been created, it is added to the Baseline Details section at the bottom of the screen.

Browse Baseline

The Baseline Details section of the Manage Baseline tab allows you to view the contents of the baseline and also to view any activities that have not been baselined yet.

The activities in the section "Activities complete but not yet baselined" are the activities that will be included in the next baseline.

For each baseline in the project you can expand the view to display the activities that were included in the baseline. You can expand or collapse the view for all baselines using the Show All and Hid All buttons.

Qualify a Baseline

The integrator can mark baselines with a status in order to indicate the quality of a baseline. A baseline that has passed testing can be marked as Good, or a baseline that has failed testing could be marked as Bad or Failed.

The following options are available by default. However, please note that the names of the status fields is configurable in the server configuration and your UCM4SVN administrator may have chosen different names:-

• Recommended
• Good
• Bad
• Untested
• Failed
• Obsolete

When a baseline is first created, its status is set to Untested. You can change the status of a baseline by selecting the desired value from the pull-down list behind the baseline name. Note that the choice will be saved immediately, and there is no need to save or submit the form.

Checkout a Baseline or a Project Integration Branch

The Manage Baseline dialogue also allows you to checkout a baseline or checkout the project integration branch. For baselines, svn export commands will be used to make sure you do not accidentally modify a baseline.

For the project integration branch, svn checkout are used. This allows an integrator to apply fixes to the project integration branch.

The checkout links provided are the same as described in the Checkout Activity subsection in the Developer section of this guide.

Note that the checkout commands text boxes are hidden in this view so as to prevent the view from becoming cluttered. You can show checkout command text boxes by clicking on a clipboard icon. Note that for baselines you will need to expand the baseline view first before the checkout commands can be shown. To hide checkout commands again, press the clipboard button again.

Recommend Baseline

An integrator can recommend a baseline to be used for a particular component on a particular project. Setting a recommended baseline for a component means that new activities will be branched off from the recommended baseline rather than the HEAD of the project integration branch.

In the example below, the recommended baseline 'b1' was set on the component 'wheel18'. When new activities are accepted by Developers, activity branches are created from the file versions that make up baseline 'b1' rather than the latest versions on the project integration branch.

Please use this feature with care as setting a recommended baseline may increase the likelihood of future merge conflicts as new activities will not include recent changes on the project integration branch.

Setting a recommended baseline can be useful when activities need to be started from a stable baseline rather than the integration branch. Please make sure you update the recommended baseline for components regularly to reduce the risk of merge conflicts in the future. The older the baseline and the more the integration branch has progressed, the more likely it is that you will encounter merge conflicts on future activities.

You set a recommended baseline by selecting Manage Baseline from the menu, selecting a project and pressing Recommend Baseline. This takes you to a new page that allows you to select the recommended baseline for each component.

You can select a recommended baseline for each component in the project. You can either use different baselines for each component, or if you would like to set the same baseline for all components, you can select a baseline from the pull-down list at the bottom of the screen to apply to all components.

Project Recommended Baseline

   Select a baseline to be used as the recommended baseline for each component.

One Baseline For All

   Choose a baseline to be used as the recommended baseline for all components.

Developer

The developer's experience of UCM4SVN is very light and non-intrusive. The basic steps are:

1. Login to UCM4SVN
2. Select the 'To Do' tab
3. Select an activity to work on by ticking the 'Accept' box
4. Select 'Take Action'. UCM4SVN will automatically create the branch for the activity from the recommended baseline specified by the 'Integrator' role
5. Check out the activity using one of the methods described below
6. Developer works on the working copy and makes as many changes as required and commits onto the activity branch as many times as required
7. When the developer has finished the development work and possibly performed a unit test:
   1. The developer will log back into UCM4SVN
   2. From the 'Activities in progress' list within the 'To Do' tab, the developer will choose one of the following options:
      1. Select 'Close' the activity, in which case the developer does not get involved in merging the code, the activity will appear on the 'Integrators' To Do list for merging
      2. Select 'Deliver' the activity, at which point UCM4SVN will attempt to merge the activity into the project integration branch and only if a merge conflict arises will the developer be asked to intervene and follow the standard Subversion merge process (more information on this later)
      3. Select both 'Close' and 'Deliver', the developer will perform a standard integration as described above but the Integrator will also have the activity available for integrating into an alternative integration branch
8. Process starts again.

Example showing two activities pending acceptance and one activity in progress

Note that when accepting, closing and delivering, activities that were created from JIRA or ClearQuest issues are moved to their next state in JIRA/!ClearQuest. However, this requires that the user performing the action has sufficient permission to progress the state of the JIRA issue or ClearQuest record.

Check Out Activity

There are four different methods of checking out an activity. When an activity is accepted, the activity branch is created and branch information is displayed on the To Do tab. You can check out an activity using one of the following methods:-

• Use the Java Checkout GUI (indicated by the Java icon, which looks like a steaming cup of coffee).
• Download a Linux checkout scripts (indicated by the Linux penguin)
• Download a Windows checkout batch file (indicated by the Windows logo)

• Cut-and-paste svn co commands into a shell window. This can be achieved by highlighting the text in the text box and copying the information or by pressing the Copy to Clipboard link. Please note that Copy to Clipboard currently works on Internet Explorer and Firefox browsers. However, for Firefox the function must first be permitted in the security settings as shown in the UCM4SVN FAQ.

Java Checkout GUI

The easiest way to check out an activity is to use the Java Checkout GUI. Please note that Java 1.5 or higher is required on the client platform for the checkout GUI.

Simply click on the link and you will be presented with the following Graphical User Interface that allows you to check out the activity:-

The Checkout GUI will have been pre-filled with workspace information and Subversion user name from the user's profile. However, this information can be changed before performing the checkout.

Simply fill in the form and press Run to perform the checkout.

UCM4SVN Activity

   This field is for information only and shows the name of the activity to be checked out. You cannot edit this field.

Workspace

   This is the target location where the Subversion workspace will be created. You can use the same workspace for multiple activities. UCM4SVN will create a subdirectory for each activity.

Add Object Name to Checkout Path

You can choose if you would like UCM4SVN to create a new directory for the object that you are checking out. For example, when checkout out an activity "tune_engine_1" into a workspace "/user/daniel/ucmwork", if you check this box, it will checkout the individual components of your project to, for example, "/home/daniel/ucmwork/tune_engine_1/exhaust". If you untick the box, it will check components out to the location specified in the workspace field, e.g. "/home/daniel/ucmwork/exhaust"

This allows you to checkout different activities to the same location, which can be useful for users of Integrated Development Environments (IDEs) such as Eclipse or Netbeans.

Subversion User Name

   Please provide your Subversion user name. Leave blank if user authentication is not required for your Subversion repository.

Subversion Password

   Please provide your Subversion password, or leave blank if user authentication is not required for your Subversion repository.

When you press Run, the checkout is started. A progress bar below the Subversion Password field indicates progress. If any errors occur, a pop-up window will show an error message. Please correct the problem and rerun the checkout.

If any of the workspaces to be created already exist, you will see the following dialogue box:-

If you select Remove Existing, it will delete the existing workspaces. However, please note that this will also delete any locally modified files that you may have in your workspaces.

If you select Ignore, it will check out over the top of your existing workspace. However, this can be very dangerous as it will not remove any files that are in your current workspace but do not exist in the repository for this particular configuration.

You can also cancel the operation using the Cancel button.

Linux and Windows Checkout Scripts

If you click on the Windows logo or the Linux penguin, you will get a Windows or Linux checkout script. These can be downloaded and run locally. The Subversion user name and workspace location are coded into the script based on the information in the user's profile, and on execution the script will prompt the user for the password.

Note that you can customise these scripts following download should you need to do so.

Copy-and-paste Checkout Commands

If you choose this option, it is recommended that you copy the commands into a script file and execute the script in order to have the opportunity to review the commands and ensure correct operation.

Having checked out a working copy, the developer can make the necessary changes using any editing tool.

View Activity Changeset

From the To-do tab, Developers can browse to an activity by clicking on the activity name, which opens the Edit Activity dialogue.

At the top of the Edit Activity dialogue is a link to the View Activity Changeset. If you click on this link, UCM4SVN will extract the changes made on the activity branch from Subversion and display the information in UCM4SVN as shown in the screenshot below.

Rebase

You can also rebase your activity branch from the To-do tab. Rebasing means that the latest changes from the project integration branch are merged into your activity branch. This gives you the opportunity to bring an activity up-to-date and merge recent changes on the project integration branch that the activity may be dependent on.

The are two different ways of rebasin an activity:-

• Default Rebase
• Custome Rebase

A default rebase will merge the project integration branch from its recommended baseline. If no recommended baseline is set, the top (i.e. head in Subversion terms) of the project integration branch will be merged.

To perform a default rebase, you can select the tick box in the Rebase column of the activity that you would like to rebase and press Take Action.

A custom rebase on the other hand gives you finer control over which versions to merge for individual components. When you click on Custom in the Rebase column of the activity that you would like to rebase, UCM4SVN will show you a new dialogue that allows you to select a baseline to rebase from for each component in the project.

On the rebase page, you can select a different baseline to rebase from for each component. Note that selecting "------" will rebase from the top (i.e. head) of the project integration branch for the component.

You can also rebase all components to the same baseline using the One Baseline for All setting at the bottom of the screen. If you select something here, the selection at the top will be ignored. Note that using the reserved item "RECOMMENDED" will rebase to the recommended baseline for the project. This is equivalent to ticking the Default Rebase tick box on the To-do page and pressing Take Action.

Integrate when Finished

There are 2 options for the Developer to complete work within UCM4SVN. The first being Close Activity the second being Deliver Activity.

Close Activity This option will not merge any of the changes onto the project integration branch but will make them available for the Integrator to Pull the changes as and when required. Effectively the activity is finished but left pending integration. If the email settings are configured, all integrators will be emailed warning them they need to take action.

Note: If this activity was created from a JIRA issue, upon being closed it will change its status in JIRA to 'Resolved' (assuming this option is enabled and using default settings).

Deliver Activity This option will merge the activity changes onto the project integration branch. The Integrator is NOT involved during the integration.

Note: If this activity was created from a JIRA issue, upon being delivered it will change its status in JIRA to 'Closed' and the closing comment will be transferred to JIRA (assuming this option is enabled and using default settings).

Close & Deliver Activity When selecting both Close and Deliver the above two apply. The common project branch will automatically be updated (subject to any merge issues) and the Integrator will also see the activity, e.g. to perform a retrospective code review.

View Baseline

Whilst developers cannot create baselines or change the status of baselines, they may need access to baselines in order to reproduce customer issues or checkout baselines as references.

Developers can browse baselines using the View Baseline tab. Select the project you would like to browse baselines for at the top and then view the baselines in the Baseline Details section.

You can expand baselines and view the activities that are part of the baseline. You can also view a list of activities that have been integrator or delivered but not yet baselined.

Using the checkout buttons, you can checkout baselines in the same fashion as on the To-do tab. However, for convenience, the text box containing actual checkout commands is hidden by default. Press the clipboard button at the end of the row of checkout buttons to show the checkout text box. Note that for baselines you will need to expand the baseline first before pressing the button.

---

Developer Merging Options

The majority of time developers will not be required to perform Subversion merging, UCM4SVN will attempt the integration (merge) and only when Subversion identifies a conflict, will the developer need to perform merge conflict resolution.

Non conflicting - trivial merge between two developers

In the following example three separate activities are being worked on and each will eventually be delivered back to the project integration branch.

1. Initially Trunk is empty

2. Developer (Activity One) creates a file F-1 in the working file and commits F-1 to Activity One branch, creating version 2. This is then merged to project integration branch creating version 3.

3. Developers for Activity Two and Activity Three check out to their working copy file F-1

4. Both make changes to the file F-1 but in different parts of the file. Activity Two adds changes X whilst Activity Three adds changes Y.

5. Developer (Activity Two) finishes first and commits changes from the working copy onto the Activity two branch creating revision 4

6. Developer (Activity Three) finished functionality Y and commits changes from the working copy onto the Activity Three branch creating revision 5

7. Developer (Activity Two) selects the Deliver option from the UCM4SVN activity list. The activity is then merged to the project integration branch for the component. This creates revision 6.

8. Developer (Activity Three) selects the Deliver option from the UCM4SVN activity list. The activity is then merged to the project integration branch for the component. Because the changes do not conflict, the merge is trivial and revision 7 holds a composite of the changes

Conflicting - merge required between two developers

1. Initially the project integration branch is empty

2. Developer (Activity One) creates a file F-1 in the working file and commits F-1 to Activity One branch, creating version 2. This is then merged back via the Deliver option to the project integration branch creating version 3.

3. Developers for Activity Two and Activity Three checkout to their working copy file F-1

4. Both make changes to the file F-1 but in different parts of the file. Activity Two adds changes X whilst Activity Three adds changes XY, where X is a conflict change.

5. Developer (Activity Two) finishes first and commits changes from the working copy onto the Activity two branch creating revision 4

6. Developer (Activity Three) finished functionality XY and commits changes from the working copy onto the Activity Three branch creating revision 5

7. Developer (Activity Two) selects the Deliver option from the UCM4SVN activity list. The activity is then merged to the project integration branch for the component. This creates revision 6.

8. Developer (Activity Three) selects the Deliver option from the UCM4SVN activity list. UCM4SVN attempts the deliver (merge) and UCM4SVN reports a merge conflict back to the developer. The Developer (Activity Three) follows the suggestions provided, see Merge Warning example below.

Merge Warning Example

Two developers working on the SAME activity cause a conflict

1. Developer-A and Developer-B are requested to work on the same activity
2. Both accept the activity and UCM4SVN automatically creates the Activity Branch.
3. Both developers create local working copies for the activity

4. Developer-A changes file F-1 and adds X

5. Developer-B changes file F-1 and changes file F-1 and creates a conflict by adding XY

6. Developer-A performs an svn commit file F-1 first, creating revision 2

7. Developer-B performs an svn commit of file F-1 and Subversion reports a merge error

8. Developer-B updates the working copy and is presented with standard Subversion merge conflict

9. Developer-B resolves the commit using standard Subversion process and selects svn resolved

10. Developer-B commits the changes creating revision 3
11. Developer-A selects the UCM4SVN deliver option first and the activity is removed from the his/her To-Do list, however nothing is delivered onto the project integration branch. Only when the last developer, in this case Developer-B selects deliver does the merge onto the integration branch take place. This will create revision 4

---

General Login

To Log In, follow the below steps.

1. Navigate to the correct URL.
2. Enter the Username registered for your account.
3. Enter your Password.
4. Click Sign In.

Edit Profile

Users are allowed to edit their profiles to change their e-mail address, password and Subversion information. This is achieved by simply logging in, and clicking the 'My Account' link in the top-right corner of the screen, next to the Logout link.

Note that users imported from JIRA cannot change their password in UCM4SVN. Please change your password in JIRA instead.

Users with the 'Project Manager' permission are also allowed to change user name, and permission settings.

Optionally, users can provide information on the their Subversion user name and default workspace location. This information is used when checking out activities using the checkout scripts or Java Checkout GUI available from the To Do tab.

Svn user name

   Subversion user name to be used for the creation of checkout scripts and as the default user name in the Java Checkout Tool. If you are using the Java Checkout Tool to check out activities, the user name provided here is only used as the default and can be overridden in the GUI.

Svn default workspace dir

   You can specify the default location to be used for UCM4SVN to create Subversion workspaces for activities. Note that a new subdirectory is created for every activity you check out, so there is no need to change this setting to keep activities separate.

   If you mainly work on Windows platforms, please specify an absolute path including the drive letter, e.g. "C:\Documents and Settings\Daniel\My Documents\ucm4svn_workspace". If you mainly work on Linux platforms, please specify an absolute path to the location of your workspace, e.g. "/home/daniel/ucm4svn_workspace.

   If you are using the Java Checkout Tool to check out activities, you can override the workspace location from the GUI.

Appendix

Appendix A: Data Migration

This section applies to users migrating from pre-2.0 releases of UCM4SVN as well as users with non-UCM4SVN data, which they would like to migrate into UCM4SVN 2.0.

UCM4SVN 2.0 is a new generation of the tool, which has seen substantial changes in the organisation of components, projects and activities. The focus has changed from components to projects, resulting not only in changes to the organisation of data in the UCM4SVN database but also the data organisation in the Subversion repository.

Due to this, automatic data migration from previous releases would be very risky and is therefore not provided.

The migration procedure is as follows:-

TODO: Expand on bullet points

• Create a Subversion workspace for your existing data by exporting your existing repository to a file system location

   mkdir old_data
   cd old_data
   svn export http://subversion.mycompany.com/svn/repos

• This will create a complete copy of the repository including tags and branches.
• Create users, components and projects in a clean, blank UCM4SVN installation and Subversion repository.
• Create a new "import" activity
• Checkout the import activity
• Copy data into import activity workspace
• Commit data
• Deliver activity

}}}