Name Modified Size Downloads / Week Status
rtc_clearcase_workspace_sync 2013-06-12 2.7 MB 0
README 2013-05-16 65.0 kB 0
LICENSE 2013-03-18 11.6 kB 0
Totals: 3 Items   2.8 MB
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 1000’s 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 1000’s 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 vobadm’s 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) CLI’s, 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 synchroniser’s 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 (' 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, 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 don’t 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
Source: README, updated 2013-05-16

Thanks for helping keep SourceForge clean.

Screenshot instructions:
Red Hat Linux   Ubuntu

Click URL instructions:
Right-click on ad, choose "Copy Link", then paste here →
(This may not be possible with some types of ads)

More information about our ad policies

Briefly describe the problem (required):

Upload screenshot of ad (required):
Select a file, or drag & drop file here.

Please provide the ad click URL, if possible:

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

No, thanks