Skip to content

README.adoc

Latest commit

 

History

History
105 lines (88 loc) · 8.8 KB

README.adoc

File metadata and controls

105 lines (88 loc) · 8.8 KB

Tool to migrate from IBM RTC to Git

A tool made for migrating code from an existing IBM RTC stream into a Git repository. Inspired by rtc2git, but written in Java and (hopefully) faster. It is implemented as scm cli plugin.

Note: This is a fork from the public code. The intent behind this fork is to make it easier to create Jenkins builds to incrementally migrate from RTC to git on a large scale.

Prerequirements

(New) Usage

  • Run ./build.sh with an argument telling it where to find the RTC scmTools (zip or folder). That’ll build a new CLI in ./rtcScmTools.

  • Run migrateFromRTCtoGit.sh with arguments telling it how to access git & rtc, where to read from and where to write to.

(scm) Usage

  • Obtain the SCM tools (as of this documentation, we are using [scmTools-Linux64-7.0.2SR1](https://jazz.net/downloads/workflow-management/releases/7.0.2SR1?p=allDownloads "scmTools-Linux64-7.0.2SR1")) and extract them to a directory

  • Extact the scmtools zip file to a location on your machine

  • Navigate to the rtc2gitcli home directory and run ./build.sh </path/to/scmTools_you_extracted_previously>. That’ll build a new rtc2git migration plugin underneath the new scmtools structure within the "rtc2gitcli" directory and place the new jar file, "to.rtc.cli.migrate_1.0.1.jar", under: <…​/rtc2gitcli/rtcScmTools/jazz/scmtools/eclipse/plugins>

  • Create a directory on your system, this will become the directory in which you’ll load your RTC workspace initially into this directory and the Git migration process will excute within, for example: /data/rtc2git/rtc_stream_acme_sandbox

  • You need to setup a reference stream and 2 repository workspaces to trigger the changeset history for migration:

  • You will need the reference RTC stream for this history you are trying to migrate, if this is already created you can reuse that, or you can cut a new stream from the existing stream if you desire as well, we’ll call this RTC_SOURCE_STREAM

  • A source repository workspace in RTC that is set to match the exact state/history of the stream stream above, that you are trying to migrate, we will call this RTC_SOURCE_REPOSITORY_WORKSPACE

  • For the RTC_SOURCE_REPOSITORY_WORKSPACE, set the flow target to the RTC_SOURCE_STREAM stream.

  • A target repository workspace in RTC that is set to the match the exact state/history of the stream stream above, but for each component in this workspace you will need to revert the history back to "1. Initial baseline" in each one to "empty" out the history and start from the beginning to get all history. We will call this RTC_TARGET_REPOSITORY_WORKSPACE.

  • For the RTC_TARGET_REPOSITORY_WORKSPACE , set the flow target to the RTC_SOURCE_REPOSITORY_WORKSPACE workspace.

  • (PLEASE NOTE: You probably, at this point, want to create a snapshot of your RTC_TARGET_REPOSITORY_WORKSPACE workspace with all history reverted for each component to "1. Initial baseline" so you can easily revert it back in case the migration dies, for any reason, and you need to restart from scratch.)

  • You should review and set your desired migration properties, if any, from the default ones in </path/to/rtc2gitcli/home/directory>/migration.properties, you will be using these later when you perform the migration process

  • Within the <…​/rtc2gitcli/rtcScmTools/jazz/scmtools/eclipse> directory, navigate to the scm executable file and perform the following:

  • ./scm -clean, when you run this it will then show the help usage afterwards, this is normal

  • ./scm --help, verify to see the new CLI command: "migrate-to-git - migrate to git"

  • ./scm login -r <rtc_url> --nickname RTC_2_GIT_CACHE_CREDENTIALS --cache --username <your_username>

  • Then run ./scm load -r RTC_2_GIT_CACHE_CREDENTIALS --directory </path/to/local/rtc/sandbox/directory/created/earlier> --all --include-root --force --allow <target_rtc_repository_workspace_name>

  • Run ./scm migrate-to-git -r RTC_2_GIT_CACHE_CREDENTIALS -d </path/to/local/rtc/sandbox/directory/created/earlier> --include-root --sourceStream <rtc_stream_name> --username <your_username> --migrationProperties </path/to/rtc2gitcli/home/directory>/migration.properties <source_rtc_repository_name> <target_rtc_repository_name>

  • This will pull in the changes from source RTC repository workspace to the local sandbox in which you’ve already loaded the empty target RTC repository workspace contents into and begin migration.

  • Finally, configure your Github/Bitbucket repository to prepare to push the code up, navigate to </path/to/local/rtc/sandbox/directory/created/earlier> and perform the following:

  • Remove any origin setting: git remote remove origin

  • Add the new remote origin to your server Git repo you’ll be pushing this to (using BitBucket as an example): git remote add origin https://git.server.com/bitbucket/scm/project/repo.git

  • Push all branch history: git push -u origin --all

  • Push all tag history: git push --tags

(Old) Manual Usage

  • create an source RTC workspace with flow target and components as wanted → SOURCE_WORKSPACE

  • create an target RTC workspace with SOURCE_WORKPSACE as flow target → TARGET_WORKSPACE

  • check comments at configure rtc workspaces

  • open shell or cmd

  • step into the target directory

  • load the initial target workspace:

scm load -r <uri> -u <username> -P <password> <TARGET_WORKSPACE>

Execute the actual migration:

scm migrate-to-git -r <uri> -u <username> -P <password> -m <migration.properties> <SOURCE_WORKSPACE> <TARGET_WORKSPACE>

How does it work?

  1. It initalizes an empty git repository and clones it

  2. In this repository, it loads TARGET_WORKSPACE RTC workspace

  3. Every change set is accepted

  4. If there is a baseline on the change set, a tag is created on git

  5. The change set is committed to git

Setup Eclipse development environment

In order to enhance the the migration tool, fix a bug that you may encounter or simply want to run it from your eclipse, here are the steps to set up a development environment:

  • Import Code Style (Window→Preferences→Java→Code Style→Formatter) eclipse-rtccli-format-settings.xml in order to have a common coding style (you can skip this step if you only want to run it)

  • Configure SCMTools Target Platform described here in the wiki. Point to the folder where your scm.exe/lscm.bat is (If you use eclipse classic aka non javaee eclipse, install the Eclipse Plugin Development Tools as described here)

  • Clone this repo and import it in eclipse as maven project

  • Open pom.xml and follow the hint to install the missing maven connector

  • Update maven project using [ALT]+[F5]

  • By this point the project shouldnt contain any errors (make sure you have still your created target platform in window preference selected)

  • You should have an launch-configuration named rtc2git → start it

  • In your console window you should see "Help for: scm migrate-to-git"

  • Open the launch-config and edit the command in arguments/program arguments

In case you use RTC Version 6+ (and have the error Problem running 'help', unknown Subcommand…​), please follow the instructions of this issue-comment in order to run rtc2gitcli.

Wiki

For more details visit our wiki

Contribute & Feedback

Feel free to report and/or fix issues or create new pull requests