1. Introduction
===============
IBM Rational Team Concert (RTC) uses a separate Jazz SCM component for out-of-the-box
Software Configuration Management (SCM) and this is packaged under RTC and referred to
as RTC Source Control. RTC also provides ClearCase connector software that includes a
"ClearCase synchroniser", which allows the bi-directionally synchronisation of data
between the two source control management systems, however, when tested we found that it:
* Requires an exclusive lock of a ClearCase branch, which means existing development
branches cannot be used. As such, normalisation of existing branches to a new
"synchronisation branch" is required, which introduces an "administration overhead"
of having to write and run "find merger" scripts to merge changes between the two
applications.
* Is not dynamic and has to be run as a scheduled Jazz Build Engine (JBE) task, which is
far from ideal as "changes" need to be dynamic.
* Is "ideally" suited to the synchronisation of data that exists in a ClearCase Unified
Change Management (UCM) configured windows environment.
2. The "RTC ClearCase workspace synchroniser"
=============================================
The "RTC ClearCase workspace synchroniser" (the synchroniser) is a Linux/UNIX based
tactical solution written to address the issues highlighted in the introduction. In
particular, it allows base ClearCase sub-directory components/products to be
bi-directionally synchronised with RTC source control Components in real-time. It also has
the ability to bi-directionally synchronise changes with central Git Hub repositories.
Notes:
i. The synchroniser runs as a daemon process and deals with changes as and when they
occur, obviously, if 1000s of files are added to source control then there will be delays
in synchronisation as this amount of data takes time to process.
ii. The synchroniser has been successfully stress-tested with many 1000s of files of
varying sizes up to an individual file size of 600MB.
3. Glossary
===========
CLI = Command Line Interface
JBE = Jazz Build Engine
JTS = Jazz Team Server
MIME = Multimedia Internet Mail Extensions
POC = Point Of Contact
RTC = Rational Team Concert
SCM = Software Configuration Management
UCM = Unified Change Management
URI = Unique Resource Identifier
VOB = Versioned Object Base
4. Overview of the synchroniser core concepts
=============================================
The following statements give a brief description of how the synchroniser works for each of
the applications (RTC, ClearCase and Git). However, you first need to understand the key
concept that the synchroniser uses a RTC Local (sandbox) workspace that is actually located
inside a ClearCase snapshot view and that this snapshot view can also host local Git
repositories.
ClearCase to RTC source control synchronisation:
------------------------------------------------
The synchroniser runs a "cleartool update" for the VOB subdirectory Component in the
snapshot view and this identifies any recent changes made in ClearCase.
This activity also creates "Unresolved" changes in the RTC local (sandbox) workspace, which
the synchroniser "checks in" to its Repository workspace and then "delivers" to its "Flow
Target", RTC Project/Team owned, Stream.
RTC Project team members who have a Repository Workspace that sources the same Flow Target
"Stream" will see the changes as incoming changes Change Sets, which they then "Accept"
into their Repository and local (sandbox) workspaces.
RTC to ClearCase synchronisation:
---------------------------------
The synchroniser "Accepts" incoming "Change Sets" into its Repository workspace.
This creates changes in the ClearCase snapshot view , which the synchroniser deals with by
running the appropriate ClearCase commands to update the underlying ClearCase VOB.
Git to RTC and ClearCase synchronisation:
-----------------------------------------
If activated, the synchroniser "Pulls" changes from a linked "Git Hub" repository into the
RTC Local (sandbox)/ClearCase snapshot view workspace. For ClearCase these are dealt with
as incoming RTC Source Control Change Sets and for RTC as incoming ClearCase changes.
RTC and ClearCase to Git synchronisation:
-----------------------------------------
If activated, the synchroniser "Pushes" outgoing Component/Product changes from RTC Source
Control and ClearCase into the linked Git Hub Repository.
5. Setting up and running a synchroniser instance
=================================================
5.1. ClearCase information required to create a synchroniser instance
=====================================================================
The following ClearCase information is required, from the project area, before you can
create a synchroniser instance:
* The name of the ClearCase VOB(s) where they store their code.
* The sub-directory location(s) in the VOB(s) that contain the Component(s)/Product(s) that
they want to bi-directionally synchronise with RTC source control.
* The name of the "ClearCase branch" that the Component(s)/Product(s) are currently
developed on. Note: This can be the main branch for small teams.
* A location in a ClearCase VOB from where new Component(s)/Product(s) will be
automatically added to the synchronisation process.
Note: During the setup process any ClearCase VOB sub-directory location can be linked to an
RTC Source Control Component, however, once the synchroniser is running it needs a set
location from where it can automatically add and the synchroniser centent.
If the need to synchronise a Component/Product outside this location arises then simple
stop the synchroniser add then sub-directory manually and then restart the synchroniser.
5.2. Quick guide to creating a synchroniser instance
====================================================
The following is a list of the steps required to create a synchroniser instance.
Note: The quick guide assumes you understand the process and only covers RTC Source
Control/ClearCase bi-directional synchronisation. For more information read the "in detail"
section:
In ClearCase logged on as the user that will run the synchroniser (vobadm):
---------------------------------------------------------------------------
1. Create a ClearCase snapshot view where you are advised to use the following naming
convention:
<project>_<activity>_synchroniser_snapshot_view
2. Logon to the ClearCase View server host and proceed as follows:
newgrp <VOB primary group>
umask 007
cd /snapshot_views/<synchroniser_snapshot_view>/vobs
Edit the ClearCase snapshot view config spec adding the appropriate ClearCase branch and
load rule(s):
cleartool edcs
Closing the "cleartool edcs" editor will, if the config spec is correct, load the data into
the snapshot view. We then need to ensure that the permissions are correctly set for the
newly added data:
chown -R <user> .
chgrp -R <VOB primary group> .
chmod -R 770 .
In RTC logged on as the user that will run the synchroniser (vobadm):
---------------------------------------------------------------------
3. Ensure the user (vobadm) that will run the "synchroniser" is a member of the RTC
Project/Team that owns the RTC SCM objects.
4. Identify the RTC Source Control Stream being used for development and if necessary
create a new one using the following suggested convention:
<project>_<branch name>_stream
Ensure the Steam is owned by the RTC Project/Team
5. For new Component development work:
Add empty Component(s) to the Stream with the same name(s) as the VOB sub-directory
Component(s) that exist in ClearCase.
6. For ongoing Component development work:
Baseline the existing Component(s) in the RTC projects current development Stream. Suggest
using naming convention:
PRE_<PROJECT>_<ACTIVITY>_BASELINE
Add the existing Component to the new RTC SCM Stream at the Baseline defined above.
7. For both new and ongoing Component development work:
Right-click the Stream and create a new Repository Workspace for use by the synchroniser
using the following convention
vobadm_<project>_<activity>_synchroniser_workspace
In ClearCase logged on as the user that will run the synchroniser (vobadm):
---------------------------------------------------------------------------
8. Link the ClearCase VOB Component snapshot view data with RTC using "scm share" command.
scm -u y -a n share <workspace_UUID> <Component_UUID> </snapshot view/VOB pathname to
the Component>/* -r https://<hostname>:9443/ccm -P <password>
Notes:
i) the /* needs to be at the end of the Component pathname if the Component contains
Eclipse project subdirectories that need to be loaded individually into the Eclipse
client. If the Component root contains directories and files then leave off the /*
ii). the "scm share" command will have to be run for each Component being linked
9. Run "scm status" to get the status of the workspace. Note: For multiple Components you
may have to cd to different locations to do this and this will be the directory location
that contains the .jazz5 directory.
10. Depending upon the output and more importantly if this is ongoing development you may
need to run "scm checkin" to check in any data updates from ClearCase. (Note: For multiple
Component or even multiple sub-directory locations you may need to run the command from
several locations):
scm checkin -n .
11. Deliver the changes (i.e. the data that has been added by the share activity)
scm deliver
This will deliver the data changes into the RTC SCM Stream ready for use. (This has to be
run from the Component location so may need running several times):
12. Create the synchroniser instance using:
./rtc_clearcase_workspace_sync --CONFIG
13. Start the synchroniser instance from the control file area with:
./sync start
and if everything runs ok create a post import RTC project Component Baseline using the
following suggested convention:
POST_INITIAL_IMPORT_<PROJECT>_<ACTIVITY>_BASELINE
5.3. Synchroniser creation in detail
====================================
Note: the following section is based around the ClearCase "vobadm" (VOB Administration
account) owning the ClearCase VOB and running the synchroniser process.
In ClearCase:
-------------
a). Create a ClearCase snapshot view using the following suggested naming convention:
<project_name>_<activity>_synchroniser_snapshot_view
Note: The naming convention is not mandatory but it makes sense to use a common naming
convention. You could also add the Activity if required (i.e. "_pilot_" , "_live_",
_maintenance", dev" etc... after the project name if applicable to make the snapshot view
more easily recognisable.
b). Logon to the server that hosts the snapshot view and use:
newgrp <VOB primary group name>
to change the current shells primary group to that of the VOB. Note: If the VOBs primary
group is not on the synchroniser users (vobadm) secondary group list then you need to use a
utility like "sugrp" to create the correct owner group configuration. So as root run:
#sugrp <VOB Owner> <VOB primary group>
It also makes sense to set the umask as follows to ensure "rwx" (Read, Write, Execute) for
the owner and group but "No" access to others(world):
umask 007
Update the ClearCase snapshot View "config spec" with the required ClearCase branch
information and load rules:
(Suggestion: Take the config spec the project is currently using to deliver code to their
development/integration branch)
cd /snapshot_views/<synchroniser_snapshot_view>/vobs
Edit the config spec and add the projects ClearCase branch information. You also need to
add the appropriate "load rule/rules" for the Component sub-directory to ensure the correct
VOB data gets loaded and subsequently bi-directionally synchronised between RTC source
control and ClearCase.
cleartool edcs
Example:
# Release 5 branch
element * CHECKEDOUT
element /vobs/samecs_src/... .../synchroniser_rel_5/LATEST
element /vobs/samecs_src/... SYNCHRONISER_REL4_BRPT -mkbranch synchroniser_rel_5
element /vobs/samecs_src/... /main/0 -mkbranch synchroniser_rel_5
# catch all
element * /main/LATEST
load /vobs/samecs_src/synchroniser
When the "cleartool edcs" editor is closed it will, if the config spec syntax is correct,
load the data into the snapshot view.
c). Update the permissions in the snapshot view
The objects in the snapshot view need to have consistent permissions before we start
synchronising so cd <extended snapshot view/VOB pathname>:
Example:
cd /snapshot_views/synchroniser_release_5_snapshot_view/ vobs/ samecs_src/synchroniser
cleartool update .
Ensure that the permissions are consistent throughout the snapshot view with:
chown <VOB owner> -R .
chgrp <VOB Primary Group> -R .
chmod 770 -R .
d). On the ClearCase View server host that hosts the synchroniser snapshot View ensure a
supported version of the RTC Eclipse Client is installed (ideally matches the server) and
if necessary add the scmtools location to the $PATH variable.
export PATH=$PATH:/opt/IBM/TeamConcert/scmtools
Notes:
i) Running "cleartool lsview -l -prop -full <snapshot view name> will identify the View
server host hosts the View.
ii) The synchroniser uses the following commands to check for updates in the ClearCase
snapshot view:
# Update the View with what has changed in the VOB
cleartool update <Extended snapshot view/VOB/sub-directory Component location>
# Check for any hijacked files, which will occur when RTC updates are sent to ClearCase
cleartool ls -r -visible . | grep -w hijacked
# Check for any new files added in RTC bound for ClearCase
cleartool ls -r -visible . | grep -v Rule:
These commands:
cleartool ls -r -visible . | grep -w hijacked
cleartool ls -r -visible . | grep -v Rule:
can be used manually to check the status of the contents of the snapshot view/local
workspace that connects RTC Source Control with ClearCase.
In RTC Source Control:
----------------------
e). Ensure that the user that runs the synchroniser is a member of the RTC Project/Team.
Note: This user has to be able to write to the ClearCase VOB as well so the VOB owner is a
good idea (i.e. vobadm ).
f). If required, create an RTC Project Stream for the development project. (Note: The
Project may already have a development Stream that they want to use)
<project>_<branch name>_stream
again naming not mandatory but it is nice to have a convention.
g). Either, Create a new empty Component(s) in the Stream to match the
Component(s)identified in ClearCase
Or, if this is continuing development work for an existing Component under this New stream:
a. Create a baseline of the Component in the existing Stream using the following convention:
PRE_<PROJECT>_<ACTIVITY>_BASELINE
b. Add the Components(s) at the baseline/baselines created under i. above to the Stream
Notes:
1. The name of the Component can be and often are different it is just easier if they
match. To date they have tended to differ as projects have used the move to RTC Source
Control as an opportunity to refactor.
2. Please ensure that the ownership of the Stream and Component are correctly set to the
RTC Project or Team and that the Components access control permissions are correctly set
according to the projects requirements (i.e. private, scoped, public)
h). Create a synchroniser workspace using the following convention:
<synchroniser_process_user>_<project>>_<activity>_synchroniser_workspace
Notes:
1. Again naming not mandatory but it is good to have a convention
2. We are using the "vobadm" process account because it owns the ClearCase VOBs; therefore,
there will be no issues when writing data into the VOB via the snapshot view.
3. In the RTC Eclipse client under the RTC Project Source Control dropdown, as vobadm,
right-click the Stream and go New -> Repository Workspace
4. You do not need to load the Repository Workspace contents into vobadms local workspace
as the ClearCase snapshot view will be the local workspace once you have shared in the
data. Note: To stop the load uncheck the "load repository workspace" box on the final
load screen.
5. If you only want to synchroniser 1 or 2 Components, when many exist in the Stream: you
need to "Edit" the Flow Target for the Repository Workspace and select the "Flow only
components checked below:" button and then the appropriate Component check box.
IMPORTANT: You must also create the control file in the synchroniser control files area:
.stream_workspace_components_differ
In the synchroniser control files area for this to work.
i). Link each Component in the RTC Repository Workspace with the sandbox/ClearCase
snapshot View VOB subdirectory Component location using the "scm share" command:
scm -u y -a n share <workspace_UUID> <Component_UUID> <extended snapshot view/VOB
pathname to the Component> -r https://<hostname>:9443/ccm -P <password>
Example:
scm -u y -a n share _dBkaEB0fEeKPMLCqm4LCXw _v7lbIBXCEeGWk9R6Iu9Sbg
/snapshot_views/synchroniser_release_5_snapshot_view/vobs/samecs_src/synchroniser/* -r
https://samecs.dev.com:9443/ccm -P xxxx
Notes:
1. The easiest way to get the WORKSPACE_UUID is as follows:
Open the Eclipse "Team Artefacts" view and go to my Repository Workspace right-click the
required Repository Workspace and select Open. In the window that appears right-click
the Stream object (top left) and select "Copy URL" and paste the into a text editor
https://samecs.dev.com:9443/ccm/resource/itemOid/com.ibm.team.scm.Workspace
/_1hr8oG3VEeGlA-_5-5kCuQ
The Repository Workspace UUID is the last entry on the line.
2. The easiest way to get the COMPONENT_UUID (and Stream UUID) is as follows:
Open the RTC web client go to the RTC Project -> Source Control and select the Stream and
then a Component. If you then copy and paste the URL into a text editor:
https://samecs.dev.com:9443/ccm/web/projects/End%
20Product#action=com.ibm.team.scm.browseElement&workspaceItemId
=_BJcY8KvzEeKE8M0emrpgkw&componentItemId=_v7lbIBXCEeGWk9R6Iu9Sbg&path=/
The COMPONENT_UUID is the last entry on the line and the STREAM_UUID is the one before.
3. Components that contain just Eclipse project sub-directories should be added with an
<extended snapshot view/VOB pathname> that ends .../*
i.e. .../webservices/src/java/*
The will ensure the sub-directories in the Component get loaded as separate Eclipse
projects rather than as a single Eclipse project under a root folder in Eclipse.
4. If there is a directory hierarchy structure in the extended snapshot view/VOB
path then add those in the synchronisation root last. Example:
.../vobs/samecs/src/webservices/src/java
before
.../vobs/samecs/src/webservices/scripts
and
... /vobs/samecs/src/webservices/utils)
5. If you do get this wrong then temporarily rename the blocking .jazz5/ directory which
will allow the child sharing to go ahead.
Example:
mv ../vobs/samecs/src/webservices/scripts/.jazz5/ ../vobs/samecs/src/webservices/scripts
/.jazz5_tmp/
scm -u y -a n share ....
mv ../vobs/samecs/src/webservices/scripts/.jazz5_tmp/ ../vobs/samecs/src/webservices
/scripts/.jazz5/
j). If this is ongoing development work of an existing Component then "scm share" activity,
described above, will result in "Unresolved" changes in the sandbox/Local
Workspace/ClearCase snapshot view, which need "checking in" therefore, run:
scm checkin -n .
Note: You will need to run this from multiple locations in multiple Components are involved.
k). Deliver the changes that the share you have just run will have created using the "scm
deliver" command.
vobadm@scoria$ scm deliver
Password (vobadm @ https://samecs.dev.com:9443/ccm/):
Delivering changes:
Workspaces:
(1184) "vobadm Synchroniser Release synchroniser workspace" --> (1192) "Synchroniser
Release 5"
Components:
(1193) "Synchroniser"
Note: You will need to run this from multiple locations in multiple Components are involved.
l). Finally check that everything is ok by running and "scm status" command, which should
give the following type of output that indicates everything is up to date.
vobadm@obsidian$ scm status -v -w
Workspace: (1184) "vobadm Synchroniser Release t synchroniser workspace" --> (1192)
"Synchroniser Release 5"
Component: (1193) "Synchroniser"
Baseline: (1200) 1 "Initial Baseline"
Note: You will need to run this from multiple locations in multiple Components are involved.
Alternative RTC Source Control method
-------------------------------------
Everything under the section above assumes that the data starts in ClearCase and will be
shared/loaded into RTC source control, which is currently the norm. However, it is
perfectly acceptable to start with the data in RTC Source Control and share/load this into
ClearCase using the following steps:
a). Add the RTC Stream Component to the synchroniser Repository Workspace with:
scm workspace add-comp <Component_UUID>
b). Accept the new Component into the Repository Workspace with:
scm accept -C <Component_UUID>
c). Load the data into the workspace/snapshot view ready to be added to ClearCase:
scm load --force <workspace_UUID> <new_Component_UUID> -d "<snapshot view new component
(parent directory) location>" ...
d). Share the Component with everyone else in the team with:
scm share <workspace_UUID> <new_Component_UUID> "<snapshot view new component (parent
directory) location><new_component>"
e). Deliver the Share with:
scm deliver
The following additional steps will also be required in ClearCase:
------------------------------------------------------------------
f). Add the view private data in the ClearCase snapshot view to ClearCase source control.
5.4. Creating a synchroniser instance
========================================
You create a synchroniser instance by running:
./rtc_clearcase_workspace_sync --CONFIG
in this mode (--CONFIG) the synchroniser will prompt you for the 8 arguments, which are
required by the synchroniser at "runtime".
5.4.1. Synchroniser setup - required arguments in the order requested by the synchroniser:
===========================================================================================
After checking that the server you are running on is capable of supporting the synchroniser
by validating the RTC SCM CLI, the synchroniser will prompt you for the following 8
arguments. Note: Argument variable name used by the synchroniser is given in brackets
i.e.($LOGPATH):
1.(a) A unique none source control UNIX/Linux directory location ($LOGPATH).
Note: This should be a file share with both Network File System (NFS) and Common Internet
File System (CIFS) access as it used by the synchroniser for control files, which are
accessed via both Linux/UNIX and Windows. For SAMECS usages we have defined this to be a
subdirectory beneath:
/snapshot_views/sync/
(i.e.. /snapshot_views/sync/<project name> )
1.(b) You will then be asked for the CIFS domain name and offered a default
(samecs.dev.com), which you can accept by hitting "Return".
From this entry the synchroniser will attempt to calculate the CIFS share equivalent of the
UNIX/Linux LOGPATH you entered under 1. (a)
(i.e \\samecs.dev.com\snapshot_views\sync\<project-name> )
which you can accept by hitting "Return".
Note: The CIFS share is required by the postop lnname trigger, which runs a Perl script
that tracks windows "cleartool mv source target" commands.
2. The synchronisation root directory ($SYNCROOT).
Notes:
i) This will be the directory location in the extended ClearCase snapshot view/VOB pathname
and should be the highest common point in the directory structure from where all
synchronised Component objects in ClearCase can be accessed.
ii) If the synchroniser is synchronising multiple VOBs this will be the .../vobs/...
directory.
An example of an extended ClearCase snapshot View/VOB/sub-directory location is given below:
/snapshot_views/SAMECS_sync_snapshot_view/vobs/SAMECS/jazz/rtc/tech/imp/src
Note: The synchroniser then validates your entry to see it exists before continuing.
3. The Jazz Repository URI of the Jazz Team Server ($REPHOST). You will be offered a
default that you can accept by hitting "Return".
(i.e. https://samecs.dev.com:9443/ccm)
4. The administrators email address to which emails issued by the synchroniser can be sent
($EMAIL). You will be offered a default that you can accept by hitting "Return".
(i.e. support@samecs.dev.com)
5. The location of the password file that contains the password of the (vobadm) processing
user used by the synchroniser ($PASSWDFILE). You will be offered a default that you can
accept by hitting "Return".
(i.e. /home/vobadm/vobadm_passwd.txt)
6. The extended ClearCase snapshot View/VOB pathname location where any new Components
created in RTC should be created in ClearCase and where any new sub-directories added in
ClearCase will result in an RTC Source Control Component of the same name being created.
($NEW_COMPONENTS_LOCATION)
Notes:
a) This will be the same as the $SYNCROOT if you are using a single VOB with Components
contained in a single directory and this will be offered as a default that you can accept
by hitting "Return".
b) If you do not want new Components to be synchronised then create a dummy directory in
ClearCase (i.e. /vobs/SAMECS/sync_null) and enter this as the New Components location.
Likewise in RTC open the vobadm synchroniser workspace and ensure that the Flow Target for
the works space is a selected list of Components. (i.e. Open Flow Target Stream and then
edit to select the Components you want to synchronise).
At this point the synchroniser will validate this entry to ensure that it is a valid RTC
Source Control share location by logging on to the Jazz Team Server (JTS) with the Jazz
Repository URI and password you have supplied in arguments 3 and 5.
7. The parent directory location from where the synchroniser will run ($SCRIPT_LOCATION).
You will be offered a default that you can accept by hitting "Return".
(i.e. /snapshot_views/SAMECS_admin _snapshot_view /vobs/SAMECS/jazz/rtc/imp/src
/rtc_base_clearcase_ workspace_synchronisation)
8. The primary group for the ClearCase VOBs being synchronised ($GROUP). You will be
offered a default that you can accept by hitting "Return".
Synchroniser instance creation and configuration
------------------------------------------------
Once you have entered the 8th argument the synchroniser will continue the setup and
configuration process by:
a). Attempting to calculate he $VOBSROOT location (The part of the in the extended snapshot
view/VOB pathname up to and including where ../vobs/... occurs.
i.e. /snapshot_views/synchroniser_evaluation_snapshot_view/vobs)
which it uses to check the existing triggers on the VOB to see if they could potentially
conflict with the running of the synchroniser
For example, if it finds any triggers that use a "clearprompt", which may attempt to
interact with the synchroniser, it will display the trigger information and ask if you want
to proceed or terminate to allow you to take remedial action (i.e. remove the trigger or
set ClearCase environmental variables to stop the trigger interacting with the
synchroniser).
Another option would be to add -nuser vobadm so that the trigger does not fire for the
synchroniser that is run by the vobadm user.
b). Continuing its setup process and creating the log (.synclog), control and metrics files
and applying the ClearCase triggers, etc... that it will need at runtime.
c). Attempting to populate the "components" file, which it does by checking the "scm
status" of the extended ClearCase snapshot view/VOB Repository Workspaces for Component
entries. At this point you will be prompted to either edit of accept what it has found. It
will be presented to you in the format:
<$WORKSPACE_UUID>*<$COMPONENT_UUID>*<Location relative to $SYNCROOT>
and this format is fully explained in section "Control Files and synclog"
d). Finally, getting the synchroniser to list the "Flow Target" Stream (STREAM_UUID) for
the synchroniser Repository Workspace, which it does by listing the Streams.
Note: The easiest way the Stream_UUID is to open the Eclipse Team Artefacts view, select
the drop-down box for the RTC Project and under "Source Control" right-click on the Stream
for the synchroniser and select Open. In the window that appears right-click the Stream
object (top left) and select "Copy URL" and paste the into a text editor
https://samecs.dev.com:9443/ccm/resource/itemOid/com.ibm.team.scm.Workspace
/_BJcY8KvzEeKE8M0emrpgkw
The Steam UUID is the last entry on the line.
This completes the synchroniser setup and configuration process and you will be given the
option to either start the synchroniser instance or Exit.
Do you want to start the synchroniser now? Y/N
Notes:
i. The synchroniser stores the arguments entered in a file called "config" that is stored
in the logs/control files (LOGPATH) location and this file is sourced at runtime and is
reused if you rerun the synchroniser with the --CONFIG option:
./rtc_clearcase_workspace_sync --CONFIG
ii. An additional 9th argument of --TEST will run the synchroniser in standalone test mode
and this is set a runtime as describe in the "Running a synchroniser instance" section
below.
5.5. Running a synchroniser instance
========================================
Daemonized script
-----------------
Once you have completed the "rtc_clearcase_workspace_sync --CONFIG" setup process, the
synchroniser will use the argument information to build a working synchroniser instance,
which can be run as daemon process that is controlled from the logs/control files
($LOGPATH) location with:
./sync start
./sync restart
./sync stop
Note: We have defined "/snapshot_views/sync" to be the parent directory control files
location and it contains a sub-directory for each synchroniser instance, therefore, by way
of example:
/snapshot_views/sync/synchroniser_evaluation
is the logs/control files location for the synchroniser_evaluation instance of the
synchroniser.
Non-Daemonised script
---------------------
If you run the synchroniser with the following options it runs in a standalone mode and
sends its output to the screen as well as the log files. This is a useful option for
debugging and use during the infancy of a new synchroniser:
./sync start --TEST
./sync restart --TEST
Updating an existing synchroniser instance
------------------------------------------
You can also rerun the initial "rtc_clearcase_workspace_sync --CONFIG" for the
synchroniser instance by running:
./sync -CONFIG
This will take your initial responses for each of the 8 arguments and prompt you for
acceptance or editing, so this is how you would update a synchroniser instance.
5.6. Concurrency of the Jazz SCM CLI
=======================================
By default Jazz SCM creates a ".jazz-scm" directory in the users (vobadm) home directory,
however, if home directories are shared across servers (the default for SAMECS) or if you
are running multiple synchroniser on one servers, again something that will happen on
SAMECS, then you need to have a per-user local copy of .jazz-scm and this is achieved by
the synchroniser by creating a local copy in the following location:
/tmp/<USER>/<SYNCHRONISER INSTANCE NAME>/.jazz-scm
when copying the .jazz-scm directory structure if there are any references to existing
daemon (lscm) CLIs, which are stored in the .jazz-scm/daemons directory, they are deleted.
5.7. Concurrency in general
===========================
Concurrency when synchronising applications is a big issue and the synchroniser has been
thoroughly tested in this area. For instance, changing the contents of a file before it is
then renamed and moved to a new location, as part of the same operation (Change Set), has
been fully tested to ensure it get mirrored correctly between RTC Source Control and
ClearCase, as has, updating numerous objects in various sub-directories before then
renaming and moving the main parent directory.
Note: Git is not a version control system in the traditional sense and, as such, it relies
on file-system commit snapshots and not version deltas; therefore, for instance, the "git
mv" command does not actually rename or move a file it basically deletes and then adds a
new file so the synchroniser has top mirror this is the same fashion (delete and then add)
when synchronising Git with both RTC Source Control and ClearCase
5.8. Log/Control Files location
==================================
The Log/Control Files location is home to the synchroniser logs and a large number of
configuration/transient files used by the synchroniser. The following is a list of the most
important files:
components
----------
The most important control file is the "components" file and the format for the contents of
the components file is:
<workspace_UUID>*<Component_UUID>*<Component Location>
Example:
_bd3OcC0-EeClbY5-9MLdDw*_wsC0MAdyEeCHkf0O7NsKcg*samecs/releases*/-
_bd3OcC0-EeClbY5-9MLdDw*_wsbOsAdyEeCHkf0O7NsKcg*samecs/rpms
_bd3OcC0-EeClbY5-9MLdDw*_wtgz0AdyEeCHkf0O7NsKcg*samecs_web/webGuis/website/MajorWeb/*
_bd3OcC0-EeClbY5-9MLdDw*_wuS28AdyEeCHkf0O7NsKcg*samecs_web/webGuis/wingdings*/-
Notes:
i. The <Component Location> is the Components pathname relative to the synchroniser defined
synchronisation root ($SYNCROOT) location in the extended ClearCase snapshot view.
Example:
Full path to Component si:
/snapshot_views/synchroniser_release_5_snapshot_view/vobs/samecs_src/synchroniser
$SYNCROOT:
/snapshot_views/synchroniser_release_5_snapshot_view/vobs/samecs_src/
Component:
Portal
Component Location:
src/synchroniser
ii. An additional */- at the end of the line allows the sub-directories of the Component to
be loaded as Eclipse projects. This is the standard configuration when the synchroniser is
running and new Components are added.
iii. The synchroniser creates a copy of the "components" file called "components_copy",
which can be .
iv. in --CONFIG mode the synchroniser attempts to build this file, however, I would advise
you review and where necessary edit this file before starting the synchroniser for the
first time
defaults
--------
The synchroniser creates a defaults file based on the "defaults" entries in SECTION 1 of
the synchroniser and these are the default values offered to the user when a new
synchroniser instance is created.
WINDOWS_DOMAIN="samecs.dev.com"
JAZZ_URI="https://samecs.dev.com:9443/ccm"
JAZZ_SCM_CONFIG="/tmp/vobadm/synchroniser_v4_0_2_testing"
ADMIN_EMAIL="support@samecs.dev.com"
RETURN_EMAIL_ADDRESS="support@samecs.dev.com"
EMAIL_RETURN_ADDRESS_FORMATTING=" -- -f "
CLASSIFICATION_HEADER=""
CLASSIFICATION_FOOTER=" "
EMAIL_CLASSIFICATION_SET="YES"
CONTROL_FILES_PARENT_DIRECTORY_LOCATION="/snapshot_views/sync"
SNAPSHOT_VIEW_VOB_LOCATION="/snapshot_views/synchroniser_evaluation_snapshot_view/vobs"
PASSWORD_FILE_LOCATION="/home/vobadm/vobadm_passwd.txt"
SYNCHRONISER_RUN_FROM_LOCATION="/snapshot_views/samecs_admin/vobs/samecs_src/synchroniser"
SCRIPT_NAME="rtc_clearcase_workspace_sync"
EMAIL_USER="support@samecs.dev.com"
RUNNING_AS_USER="vobadm"
PRIMARY_GROUP="ngcc_u"
SCMTOOLS_DEFAULT="/opt/IBM/TeamConcert/scmtools/eclipse"
SCMTOOLS_ALTERNATIVE="/opt/IBM/TeamConcertBuild/scmtools/eclipse"
config
------
This file, amongst other things, contains a copy of the 8 input argument used by the
synchroniser and if the config exists these arguments are sourced and passed back to the
synchroniser for reuse when running the following synchroniser configuration commands:
./sync --CONFIG
./rtc_clearcase_workspace_sync -CONFIG
An example of a config file is shown below:
LOGPATH="/snapshot_views/sync/synchroniser_v4_0_2_testing*\\\\samecs.dev.co\\snapshot_views
\\sync\\synchroniser_v4_0_2_testing"
SYNCROOT="/snapshot_views/rtc_clearcase_workspace_synchroniser_rtc_v4_0_2_testing
_snapshot_view/vobs/synchroniser_evaluation"
REPHOST="https://samecs.dev.com:9443/ccm"
PASSWDFILE="/home/vobadm/vobadm_passwd.txt"
NEW_COMPONENTS_LOCATION="/snapshot_views/rtc_clearcase_workspace
_synchroniser_rtc_v4_0_2_testing_snapshot_view/vobs/synchroniser_evaluation"
SCRIPT_LOCATION="/releases/rtc"
GROUP="ccadm_u"
EMAIL="support@samecs.dev.com -- -f support@samecs.dev.com"
RETURN_EMAIL_ADDRESS="support@samecs.dev.com"
EMAIL_RETURN_ADDRESS_FORMATTING=" -- -f "
CLASSIFICATION_HEADER=" "
CLASSIFICATION_FOOTER=" "
EMAIL_CLASSIFICATION_SET="YES"
EMAIL_USER="support@samecs.dev.com"
STREAM_UUID="_AfRT4KEZEeKa_tNjWqU9zA"
SCMTOOLS="/opt/IBM/TeamConcert/scmtools/eclipse"
STARTING="NO"
SYNC_BRANCH="rtc_clearcase_workspace_synchroniser_v4.0.2"
RUNNING_AS_USER="vobadm"
metrics.txt (One at the Component level and one at the synchroniser level)
--------------------------------------------------------------------------
These, comma delimited, files store metrics information of the synchronisers activities in
the following format:
Date&Time,SynchroniserInstance,Component,Direction,Command,Action,NumberOfFiles,Data,TimeTaken
23_06_11@06_53_00:,samecs,Access_products_java,ClearCase->RTC,"scm -u y -a n
checkin",---c,28,0,10
23_06_11@15_01_36:,samecs,Samecs_elements_cpp,ClearCase->RTC,"scm -u y -a n
checkin",--a-,2,4503,12
23_06_11@15_28_28:,samecs,Samecs_elements_cpp,ClearCase->RTC,"scm -u y -a n
checkin",---c,3,1774,11
23_06_11@15_33_26:,samecs,Samecs_elements_lib,ClearCase->RTC,"scm -u y -a n
checkin",-dac,30,75266,14
23_06_11@15_42_28:,samecs,Access_products_rpms,ClearCase->RTC,"scm -u y -a n
checkin",--ac,19,6856920,13
Heading Description
Date&Time: Date (DD_MM_YY) and time (HH_MM_SS) of the activity.
Synchroniser Instance: Name of the synchroniser instance
Component : The name of the Component being processed
Direction: Either "RTC to ClearCase" or "ClearCase to RTC"
Command: Short description of the command (i.e. scm checkin)
Action: A 4 character string highlighting what the command did:
Renamed/Moved = m---
Deleted = -d--
Added = --a-
Changed (updated) = ---c
NumberOfFiles The number of files being processed.
Data: The amount of data involved in bytes
Time Taken: The time taken for the activity in seconds.
refactor.sh & refactor.pl
-------------------------
The synchroniser installs a post operational ClearCase VOB trigger on the hidden "lnname"
ClearCase command and this allows the synchroniser to track ClearCase refactoring activity.
To implement this, the synchroniser creates two scripts: refactor.sh (UNIX/Linux) and
refactor.pl (Windows) and the one that runs is dependent upon the end-user environment
(UNIX/Linux or Windows). The data collected by the scripts allows the synchroniser to
mirror ClearCase refactoring (Rename and Move) activity in RTC Source Control.
Notes:
i.Execute permissions must exist on the scripts for the owner, group and others:
-rwxr-xr-x 1 vobadm samecs 1783 Apr 23 12:06 refactor.pl
-rwxr-xr-x 1 vobadm samecs 689 Apr 23 12:06 refactor.sh
ii. The post operational trigger uses the following naming convention:
refactor_<STREAM_UUID>
This allows multiple synchroniser to run against the same VOB but on different ClearCase
Branches/RTC Source Control Streams.
synclog
-------
Any meaningful transactions (i.e. cleartool and scm commands that create change) are logged
in the synchroniser log, which is called "synclog". You can also turn on a higher level of
logging by placing a file named ".full_logging" in the synchroniser instances control file
location.
An example of a log output is give below:
*********************************************************************
03_08_11@10_33_24: Running "scm -u y -a n accept -C rc5 test"
03_08_11@10_33_33: (See output below:)
Repository: https://samecs.dev.com:9443/ccm/
Workspace: (_8IojcKe8EeCbbt4zvI36Cg) "vobadm_synchroniser_development_workspace"
Component: (_Sv9Y0L26EeCYhu87w_ih8w) "rc5 test"
Change sets:
(_4fY9Ib27EeCYhu87w_ih8w) ---$ SAMECS <No comment>
Changes:
---c- /rc5 test/level 1 test.sh
---c- /rc5 test/Level 1/test.sh
**********************************************************************
03_08_11@10_33_33: The following files are hijacked (See output below):
level1 test.sh
./Level 1/test.sh
**********************************************************************
Running: cleartool co -usehijack | cleartool ci against the above
**********************************************************************
03_08_11@10_33_33: synchroniser metrics generated
03_08_11@10_33_33:,synchroniser_development,rc5 test,RTC->ClearCase,"cleartool co
-usehijack & ci",---c,2,13652,1
**********************************************************************
5.8.1. Other control files with a description:
===============================================
.classpath.ignore & .build.xml.ignore
-------------------------------------
When created in the control files area it allows different ".classpath" files to exist in
both the ClearCase and RTC source control environments. This control file can be set at the
synchroniser or individual Component levels.
.clearcase.ignore
-----------------
When created and populated any files named in the ".clearcase.ignore" file are ignored by
the synchroniser. This control file can be set at the synchroniser or individual Component
levels. Note: This mirrors the functionality of the out-of-the-box .jazzignore used by RTC
Source Control.
.clearcase_to_rtc_sync.ignore
-----------------------------
When created, it stops ClearCase updates being sent to RTC source control. This control
file can be set at the synchroniser or individual Component levels.
.cli_version
------------
Stores the current version of the Jazz SCM CLI and is used by the synchroniser to allow for
variance interface.
.empty
------
Identifies the data status of the Component:
* "NO" indicates that it contains data
* "YES" indicates that the Component is empty
.full_logging
-------------
When created in the control files area it turns on a high-level of logging (i.e. list all
checkout and checkins rather than a summary). This control file can be set at the
synchroniser or individual Component levels.
.get_symlinks
-------------
RTC Source Control does not fully support symbolic linking; therefore, when created, the
.get_symlinks control file lists the ClearCase symbolic links in the VOB sub-directory
Component that will not be reflected in RTC Source Control. For each Component the output
is sent to the file:
<$LOGPATH>/$COMPONENT_UUID/.symlinks
Note: You should not leave the ".get_symlink" flag turned on permanently as this will
affect the performance on the synchroniser.
.git_sync
---------
If the file exists the synchroniser pushes RTC Source Control and ClearCase changes to a
central Git Hub repository (Component). This control file can be set at the synchroniser or
individual Component levels.
Note: A number of other steps are required to activate Git synchronisation and these are
detailed in Git synchronisation
.hostname
---------
This control file contains the "hostname" of the server for the synchroniser instance and
ensures that
* the "./sync stop" and ./sync start" are run on the correct server host.
* a second instance is not started when one is already running.
.last_run
---------
A time-stamped control file that is updated by the synchroniser before the processing of
each Component begins, which can be used to see if a synchroniser has stopped running. On
SAMECS we run an hourly cronjob of samecs.dev.com, which emails SAMECS Support if a
synchroniser instance has stopped working.
.lscm_override
--------------
If the Components being synchroniser exist at different ClearCase VOB sub-directory levels
then the synchroniser defaults to using individual "scm" commands rather than the standard
permanently running "lscm" daemon command. However, you can continue to run the "lscm"
daemon as long as the Component pathname do not overlap; therefore, the ".lscm_override"
control file was created to allows usage of the "lscm" command in such situations.
.no_component_rename
--------------------
By default a Component appears in the components files as a Component that contains Eclipse
project sub-directories (i.e. has */-" ending to the line) and, as such, the Component
named sub-directory in ClearCase and the RTC Source Control Component are linked;
therefore, if one is renamed, say in ClearCase, then it will get renamed in RTC Source
Control. There may be occasions when you want the Component to be renamed in one tool but
not in the other so creating the ".no_component_rename" control file, which can be set at
the synchroniser or individual Component levels, allows this to happen.
.no_git_pull
-----------
When this file exists in a control files area, it will stop the synchroniser running the
"git pull" command that pulls changes from the "Git Hub" repository into the RTC Source
Control and ClearCase linked Component. This control file can be set at the synchroniser or
individual Component levels.
.no_git_tag
-----------
When this file is exists in a control files area, it will stop the synchroniser running the
"git tag" command that mirrors RTC Source Control baseline in the equivalent "Git Hub"
linked repository. This control file can be set at the synchroniser or individual Component
levels.
.no_label
---------
By default RTC Source Control created Baselines generate a ClearCase mklbtype followed by a
silent mklabel of the equivalent files in ClearCase, however, if the ".no_label" control
file, which can be set at the Instance or Component level, exists the labelling activity in
ClearCase does not take place.
.poc
----
The ".poc" file is designed to hold the email addresses of the RTC Source Control/ClearCase
project related Points Of Contact (POCs). The list should contain members of the project
hierarchy that should be emailed if the synchroniser experiences any processing issues.
This control file can be set at the synchroniser or individual Component levels.
.rtc_to_clearcase_sync.ignore
-----------------------------
When this control exists it stops RTC Source Control events being sent to ClearCase. This
control file can be set at the synchroniser or individual Components level.
Note: This means that the RTC Source Control Change Sets will "backup" in the synchroniser
Repository Workspace; therefore, you should monitory the synchroniser instance closely if
this control file is removed as it could "open the floodgates" with changes bound for
ClearCase, which may take considerable time to process.
.script_run_stop
This control file contains either the word "run" or "stop" and is populated by the ./sync
start|stop|restart script options, where the "./sync stop" option changes the contents to
"stop" and causes the synchroniser to terminate after it has processed its current
Component.
.sync_branch
------------
Stores the name of the ClearCase branch being used by the synchroniser instance.
.stream_workspace_components_differ
-----------------------------------
There are occasions when the synchroniser is only required to synchroniser certain
Components in a Stream. If this is the case then you need to create
".stream_workspace_components_differ" in the synchroniser instances control files area
($LOGPATH)
.version
--------
This control file stores the version number of the synchroniser that is currently running.
It sources its information from $SYNC_VERSION variable which is defined at the beginning of
the synchroniser shell script.
5.8.2. Transient files in the control file area
===============================================
The synchroniser also creates a large number of transient files that are generated from the
"cleartool" and "scm" command outputs and these are used for logging and error trapping
purposes.
6. Synchronising RTC Source Control and ClearCase changes with a Git Hub
========================================================================
With effect v5 of the synchroniser RTC Source Control and ClearCase changes can be
synchronised with a central Git Hub repository, however, to activate the "git sync" part of
the synchroniser there are some administration level tasks that need completing first.
a). Stop the synchroniser instance:
$ cd /snapshot_views/sync/<synchroniser instance>
$ ./sync stop
b). Change directory to the extended ClearCase snapshot view/VOB/Component Linux operating
system location:
For this example the snapshot view location of the "synchroniser_evaluation_ snapshot_view"
is:
/snapshot_views/rtc_clearcase_workspace_synchroniser_v4.0.1_snapshot_view
The extended snapshot view/VOB location for the synchroniser_evaluation VOB extends this
path to:
/snapshot_views/rtc_clearcase_workspace_synchroniser_v4.0.1_snapshot_vie
/vobs/synchroniser_evaluation
And the Component is "Volcano". In this example the Component is located in the root of the
VOB giving a final extended snapshot view/VOB/Component pathname of:
/snapshot_views/rtc_clearcase_workspace_synchroniser_v4.0.1_snapshot_view
/vobs/synchroniser_evaluation/Volcano/
So cd to the extended ClearCase snapshot view/VOB/Component location, which should contain
the .jazz5/ RTC Source Control "metadata" directory.
cd /snapshot_views/rtc_clearcase_workspace_synchroniser_
v4.0.1_snapshot_view/vobs/synchroniser_evaluation/Volcano/
c). If one does not exist in this location create a .jazzignore file so that we can ignore
the Git control files
$ touch .jazzignore
and populate either the existing or new file as follows:
$ echo .git/ >> .jazzignore
$ echo .gitignore >> .jazzignore
$ cat .jazzignore
.git/
.gitignore
d). If one does not exist in this location create a .gitignore file so that Git can ignore
the Jazz control files.
$ touch .gitignore
and populate either the existing or new file as follows:
$ echo .jazz5/ >> .gitignore
$ echo .metadata/ >> .gitignore
$ echo clientdb.xml >> .gitignore
$ echo .jazzShed/ >> .gitignore
$ echo .jazzignore >> .gitignore
$ cat .gitignore
.jazz5/
.metadata/
clientdb.xml
.jazzShed/
.jazzignore
e). In the same extended snapshot view/VOB/Component location initialise (create) a local
git repository by running:
$ git init
Initialized empty Git repository
in /snapshot_views/rtc_clearcase_workspace_synchroniser_v4.0.1_snapshot_view/vobs/
synchroniser_evaluation/Volcano/.git
f). Start tracking all the objects in the "Volcano" directory by staging them ready to add
to local git repository you have just created by running:
$ git add -- all
Note: The ".gitignore" file tells git to ignore the Jazz related control files
g). Commit the staged files into the local repository by running:
$ git commit -m "Initial Commit"
[master (root-commit) 23ff378] Initial Commit
6 files changed, 79 insertions(+)
create mode 100644 .gitignore
create mode 100755 Volcano/.classpath
create mode 100755 Volcano/.project
create mode 100755 Volcano/.settings/org.eclipse.jdt.core.prefs
create mode 100755 Volcano/src/VolcanoApplication.java
create mode 100755 Volcano/src/VolcanoRobot.java
$
h). If you have not already created a Git Project and Repository that you are going to link
to the RTC Source Control Component/ClearCase sub-directory then logon to the Git Hub
Enterprise management tool, create a Project and a Repository that you are going to link to
the RTC Source Control Component/ClearCase VOB sub-directory, which in this example is
"Volcano". You now need to add the remote Repository using:
$ git remote add Volcano ssh://git@samecs.dev.com:7999/JSGS/volcano.git
Notes: You can check the remotes with:
$ git remote -v
Volcano ssh://git@samecs.dev.com:7999/JSGS/volcano.git (fetch)
Volcano ssh://git@samecs.dev.com:7999/JSGS/volcano.git (push)
Component names can be long so if you wanted to shorted the remote repository name to, say,
"vol" rather than "Volcano" you can do this by creating an "..git_remote" file in the
control files area and populating the file with the shortened name.
cd /snapshot_views/sync/synchroniser_v4.0.1_testing
Cat the components file and get the Component UUID location, which is the entry after the
first *:
cat component
....
_RGlAcGrLEeKpwdFSiAVPNQ*_v7TGsHnFEeKpwdFSiAVPNQ*Volcano*/-
....
cd to the Component UUID location:
cd *_v7TGsHnFEeKpwdFSiAVPNQ
Touch the .git_remote file and populate with the shortened remote repository name:
touch .git_remote
echo "vol" > .git_remote
If the remote already exists you can remove this with:
$ git rm Volcano
You can then add the alias to identify the remote with:
$ git remote add vol ssh://git@samecs.dev.com:7999/JSGS/volcano.git
i). Push the data committed to the local repository to the remote Git Hub repository
$ git push Volcano master
Counting objects: 11, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (11/11), done.
Writing objects: 100% (11/11), 1.68 KiB, done.
Total 11 (delta 0), reused 0 (delta 0)
To ssh://git@samecs.dev.com:7999/JSGS/volcano.git
* [new branch] master -> master
$
Notes:
1. If there are issues with the RSA key they will be highlighted at this point and can be
resolved at this time as well.
The authenticity of host 'samecs.dev.com (192.168.0.10)' can't be established.
RSA key fingerprint is 01:3c:6c:f6:9e:af:f1:34:38:20:2a:de:b6:79:6b:ca.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'samecs.dev.com,192.168.0.10(RSA) to the list of known hosts.
Counting objects: 11, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (11/11), done.
Writing objects: 100% (11/11), 1.68 KiB, done.
Total 11 (delta 0), reused 0 (delta 0)
To ssh://git@samecs.dev.com:7999/JSGS/volcano.git
* [new branch] master -> master
$
2. If you see the following error:
To ssh://git@samecs.dev.com:7999/JSGS/dmoz.git
! [rejected] master -> master (non-fast-forward)
error: failed to push some refs to 'ssh://git@samecs.dev.com:7999/JSGS/dmoz.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Merge the remote changes (e.g. 'git pull')
hint: before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
Try the following which will force the changes to be pushed:
$ git push -f Volcano master
j). Check the status of the workspace (i.e. the extended ClearCase snapshot view/VOB
/Component location) by running:
$ git status
# On branch master
nothing to commit (working directory clean)
k). Getting the RTC ClearCase workspace synchroniser to push updates to Git. Cd to the
control file area, which will be a sub-directory under:
/snapshot_views/sync
So for this example the directory is:
/snapshot_views/sync/synchroniser_v4.0.1_testing
cat the components file to get the Component UUID, in this case for the Volcano Component:
$ cat components
_RGlAcGrLEeKpwdFSiAVPNQ*_f5qPsGrKEeKpwdFSiAVPNQ*RTC_Analytics*/-
_RGlAcGrLEeKpwdFSiAVPNQ*_a0UowXnMEeKpwdFSiAVPNQ*String^Checker^renamed*/-
_RGlAcGrLEeKpwdFSiAVPNQ*_C8yy8XnMEeKpwdFSiAVPNQ*Weather*/-
_RGlAcGrLEeKpwdFSiAVPNQ*_v7TGsHnFEeKpwdFSiAVPNQ*Volcano*/-
cd to the Component UUID location, which is the second UUID in the Components file directly
before the Component name:
$ cd _v7TGsHnFEeKpwdFSiAVPNQ/
Create the .git_sync file
$ touch .git_sync
Note: If the .git_sync file is left blank then "master" will be assumed.
l). Start the synchroniser by cd ing back to the control files area:
$ cd ..
Start the synchroniser:
./sync start
Note: If you want to observer the output start the synchroniser as follows:
./sync start --TEST
6.1. Pulling changes from the Git Hub Repository
================================================
By default the synchroniser is configured to pull any changes from the Git Hub Repository
into RTC Source Control and ClearCase, however, this is not always required and can be
stopped by adding the control file:
.no_git_pull
to the control files area. This control file can be set at the synchroniser or individual
Component levels.
6.2. RTC Source Control Component Baseline mirroring to a Git Hub Repository
============================================================================
When an RTC Source Control baseline is accepted by the synchroniser, by default, it creates
a ClearCase label type based on the Baseline name and then applies it to all the equivalent
Component sub-directory files in ClearCase. In addition, if the Component is being
synchronised with a Git Hub repository then an equivalent "git tag" will be applied to all
the equivalent Component files in the Git Hub repository.
Note: Setting the .no_git_label control file stops the "git tag" operation taking place and
setting the ".no_label" control file stops both the "ClearCase label" and "git tag"
operations.
7. WARNING: Permissions are key dont manually change things in the synchroniser workspace
=========================================================================================
Once you have created the jazz scm share you are advised to manually edit anything in that
is shown as the black-box synchroniser in the diagram on the next page. For instance if
you manually check out and then check in a file into the VOB from the synchroniser
ClearCase snapshot view it will change the files permissions in such a way that the local
workspace (sandbox) see this as a change and will create a circular update.
To reiterate the synchroniser controls this behaviour with the permissions function, where
basically the permissions of a file are captured before it is updated and reset back to
exactly the same permissions after the update.
Permissions are key to the success of the synchroniser, which ensures files can be written
to when they are created or updated in the local workspace (sandbox)/snapshot view
location.
8. Maintenance of the synchroniser and what to do when it goes wrong
====================================================================
a) The synchroniser is running but is not processing anything.
--------------------------------------------------------------
Stop the synchroniser "./sync stop" if that does not work run "ps -ef | grep scmtools" and
kill the ones that are still running.
Note: If there is an outgoing Change Set with not comment stop the synchroniser cd to the
extended snapshot view VOB location and set the Change Set comment with:
scm -u y -a n changeset comment <Change Set UUID> "<suitable comment>"
scm deliver <Change Set UUID>
b)The synchroniser reports that the "Local file system is out of sync." --
--------------------------------------------------------------------------
*** Run scm load -force <$WORKSPACE_UUID>
-----------------------------------------
As the output below highlights in the last line you need to run and scm load -force
<WORKSPACE_UUID> < COMPONENT_UUID>
vobadm@jade$ scm status -v -w
Local filesystem is consistent.
Password (vobadm @ https://samecs.dev.com:9443/ccm/):
Workspace: (0918) "vobadm Synchroniser Release 5 Workspace" <-> (0919) "Synchroniser
Release 5"
(vobadm @ https://samecs.dev.com:9443/ccm/)
Component: (0920) "Synchroniser" <-> (0919) "Synchroniser Release 5"
Baseline: (0921) 70 "POST_CLEARCASE_IMPORT_RELEASE_4"
Incoming:
Change sets:
(0935) ---$ xxxx xxxx 212072 "Modification logic needs to apply when editing saved
draft modification" - <No comment>
(0922) ---$ xxxx xxxx 212366 "Fix wrapping of text for long report titles in
Editor LaunchPad widget" - <No comment>
...
...
Some components in (0918) "vobadm Syncroniser Release 5 Workspace" are out of sync.
(0920) "Synchroniser"
Local filesystem is out of sync. Run 'scm load' with --force option to reload the
workspace.
Which can be resolved by running "scm load -force <WORKSPACE_UUID>" or for an individual
Component with: "scm load -force <WORKSPACE_UUID> <COMPONENT_UUID>"
vobadm@jade$ scm load --force 0918 0920
Password (vobadm @ https://samecs.dev.com:9443/ccm/):
Downloading /xxxx/.jazzignore (772 B)
Downloading /xxx-source.jar (2.0 KB)
...
Rechecking the status now shows that the synchroniser workspace in now back in sync ready
for being used by the synchroniser
vobadm@jade$ scm status -v -w
Local filesystem is consistent.
Password (vobadm @ https://samecs.dev.com:9443/ccm/):
Workspace: (0918) "vobadm Synchroniser Release 5 Workspace" <-> (0919) "Synchroniser
Release 5"
(vobadm @ https://samecs.dev.com:9443/ccm/)
Component: (0920) "Synchroniser" <-> (0919) "Synchroniser Release 5"
Baseline: (0921) 70 "POST_CLEARCASE_IMPORT_RELEASE_4"
Incoming:
Change sets:
(0935) ---$ xxxx xxxx 212072 "Modification logic needs to apply when editing
saved draft modification" - <No comment>
(0922) ---$ xxxx xxxx 212366 "Fix wrapping of text for long report titles in
....
c) How to do a manual check of a synchroniser instance
------------------------------------------------------
First cd to the synchronisation root directory e.g:
/snapshot_views/rtc_clearcase_workspace_development_snapshot_view
/vobs/synchroniser_evaluation
or if the Component only contains Eclipse project sub-directories (i.e. the line in the
$LOGPATH/components file ends in a /*-) the Component directory e.g:
/snapshot_views/rtc_clearcase_workspace_development_snapshot_vie
/vobs/synchroniser_evaluation/Volcano
Checking RTC by running:
scm -u y -a n status -v -w
What you are looking for here is the fact that the local workspace is consistent:
Local filesystem is consistent.
Workspace: (_N_WRkJN2EeG78qH6aTWnyQ) "vobadm Synchroniser Release 5 synchroniser
workspace" <->
(_FgOZwG3SEeGlA-_5-5kCuQ) "Synchroniser Release 5" (vobadm @ https://samecs.dev.com:9443
/ccm/)
Component: (_v7lbIBXCEeGWk9R6Iu9Sbg) "Synchroniser" <-> (_FgOZwG3SEeGlA-_5-5kCuQ)
"Synchroniser Release 5"
Baseline: (_bljPcpOgEeG78qH6aTWnyQ) 33 "POST_SYNCHRONISER_REL_4"
Note: The synchroniser uses the following commands to check for updates in the ClearCase
snapshot view:
# Update the View with what has changed in the VOB
cleartool update <Extended snapshot view/VOB/sub-directory Component location>
# Check for any hijacked files, which will occur when RTC updates are sent to ClearCase
cleartool ls -r -visible . | grep -w hijacked
# Check for any new files added in RTC bound for ClearCase
cleartool ls -r -visible . | grep -v Rule:
These commands can be used to check the status of the contents of the snapshot view
workspace that connects RTC source control and ClearCase
d) The synchroniser has incorrectly delivered a Change Set
----------------------------------------------------------
If the synchroniser has incorrectly delivered changes fro ClearCase to RTC then, as a RTC
Project team member open the Jazz SCM Pending Changes view accept the incoming Change Set
then open the Component History in the Pending Changes View and reverse the Change Set you
have just received. This will create a patch that should be merged with the workspace,
which will reverse the Changes and this should then be delivered to the rest of the
Projects Team members.
e) Using the RTC Eclipse client GUI to resolve issues in local (sandbox) workspace
-----------------------------------------------------------------------------------
It is perfectly acceptable to stop the synchroniser and start the RTC Eclipse client GUI as
vobadm to resolve any conflict issues:
/opt/IBM/TeamConcert/Eclipse
Note: If the synchroniser has been running the "lscm" daemonised CLI it will continue to
run once you have stopped the synchroniser. To rectify this run:
ps -ef | grep scm
vobadm 418 1 0 07:11 pts/1 00:00:08 /opt/IBM/TeamConcert/scmtools/eclipse/scm
--config /home/vobadm/.jazz-scm daemon start --connection-timeout 120000 --inactive-timeout
7200000
and kill the process#
f) A synchroniser instance will not start but no process is running to kill
---------------------------------------------------------------------------
The issue was resolved when I removed the /tmp/vobadm/<synchroniser name>/.jazz-scm instance
