1 Creating an RTC Hot Fix September 18, 2013

2 Steps for creating a hot fix Find the work item where the defect is resolved. Check for existing hot fixes. Create a target release installation. Create a repository workspace for the target release. Build. Merge. Rebuild. Create the hot fix. Test. Deliver.

3 Find the work item where the defect is resolved. Often is will be mentioned in the hot fix summary or description. Example –Hot fix request –Summary: Defect backport to

4 Check for existing hot fixes Sometimes a hot fix will be requested, and such a hot fix will already exist. The first step should be to see if a hot for already exists. Look for links on the original defect. If no links found, run a query.

5 Example Hot Fix requested –Defect backport to Look at defect –Links tab –Link tab shows Hot Fix under Related.

6 Example –But, I added it after the fact! It wasn’t there before. So, don’t give up if you don’t see a link. –Search Jazz Support (Private) project area I queried for all delivered source control hot fixes –Type is “Hot Fix” –Status is “Delivered” –Filed against in RTC-CCM->Source Control –This returned 36 work items –One of them is : Hotfix request for wi User without permission can unlock file

7 Create a target release installation. If the hot fix is client only, you might be able to get by creating only a client installation, if you can find a compatible server. For server hot fixes, you will need to create a server installation, and probably a client installation as well.

8 Example Hot fix request –Summary: PM Cannot browse baselines before the latest 1024 –Customer requested hot fix for –I did the fix for 4.0.5, so I know that the fix is client only. –So, I installed a client. C:\RTC\RTC-Client-Win-4.0.1

9 Create a repository workspace for the target release. First create a new Eclipse workspace. You don’t want to use the same Eclipse workspace you are using for Source Control Integration, because the sanddbox for the common components would be written to the same location. Workspaces –RTC-dev (for current release development) –RTC-test (for current release testing) –RTC-dev (for building hotfix) –RTC-test (for testing hotfix)

10 Create a repository workspace for the target release. Find the appropriate snapshot. Team Artifacts View –Rational Team Concert Source Control –RTC Integration stream -> Show Snapshots Find the GA snapshot for the release –Note use of RTC Integration stream, not Source Control Integration stream –Note that naming conventions changed over time

11 Example (4.0.1)

12 Example ( )

13 Example (4.0)

14 Create the repository workspace from the snapshot Don’t set a flow target. –Hot fixes do not flow to a stream. Load the appropriate components –Typical list is the following Filesystem RelEng RelEng Common RelEng RTC RelEngBuilder RTC Commons SCM Target Definitions*

15 Find the target platform Newer releases –Target Definitions component Older releases –RTC Commons component –Name might not mention “target platform” Look at history of the relevant component. Find the correct change set.

16 Find the target platform Release –Target platform is in RTC Commons component. –From the RTC Commons component in your repository workspace Show History Look for change sets near the date of the snapshot that might reference “target platform”

17 Find the target platform The GA snapshot is dated March 26, 2012

18 RTC Commons History

19 Find the target platform It looks like the change set for the target platform is this one. –"203079: [RTC] Prepare the stream for GA - end game - rtc.3x.jcb RTC-I ", "Li Zhu", "Mar 27, :35 AM“ To verify, I looked for a hot fix that Matt created on top of to see what he used for his target platform. –I compared his hot fix repository workspace with the snapshot.

20 Find the target platform

21 Find the target platform Yes, this is the correct change set for the target platform. Accept the target platform change set.

22 Find the target platform hot fix Now it’s in the Target Definitions component and is easier to find!

23 Find the target platform The change sets corresponding to target platforms are also listed on two wiki pages. –For older releases (3.X) rmForGAReleases rmForGAReleases –For newer releases (4.X) rmForGAReleases40x#RTC_4_0_1https://jazz.net/wiki/bin/view/Main/RTCTargetPlatfo rmForGAReleases40x#RTC_4_0_1

24 Build Once you have your repository workspace set up for the target release, and have chosen the correct target platform, build without your changes first. If this is successful, then you can merge in your changes.

25 Build Some errors are expected and can be ignored

26 Merge and rebuild –Find the change set or change sets from the fix you are backporting. –Accept the change set(s) into your repository workspace for your target release. –You will probably get a message telling you there are gaps, and you will get a chance to merge. –For simple changes, it is easier to re-apply the change manually, rather than accept the change set.

27 Create change set for your fix Create a new change set for your code changes. Associate your change set to the hot fix work item. When you are done, you can complete your change set, but do not deliver it to a stream.

28 Create the hot fix Existing documentation L3 Wiki page – –Two relevant sections discuss server and client hot fixes. –RTC Server Hotfix (Testfix) ProcessRTC Server Hotfix (Testfix) Process –RTC Client Hotfix (Testfix) ProcessRTC Client Hotfix (Testfix) Process Work item –Task discusses how to build an update site

29 Create the hot fix For an Eclipse client –Build an update site For RTC CLI or server –Deliver jar files In all cases, create a zip file.

30 Create the hot fix Remember to use Eclipse workspace for development, specific to the target release. Use the “Plug-in Development” perspective. Find the bundles that you need to deliver. This will tell you if your hot fix is client, server, or both.

31 Example Hot Fix PM Cannot browse baselines before the latest 1024 –Changes are in Enhancement –One change set, in Filesystem.

32 Example Two bundles –com.ibm.team.filesystem.client –com.ibm.team.filesystem.ide.ui Both are Eclipse client

33 Creating an update site Task [HOW TO] Build an Update site for the RTC 3.X Client 1.Modify bundle version in the plug-in xml version number suffix. 2.Create a new feature project. 3.Add plug-ins to the feature project. 4.Create an update site project. 5.Add the feature. 6.Save and build.

34 Example (Hot Fix ) Two bundles –com.ibm.team.filesystem.client –com.ibm.team.filesystem.ide.ui Open each project in Package Explorer or Project Explorer Open plugin.xml file Click on Overview tab

35 Xml file version

36 Old plug-in version The bundle part of the version before the date should match what is in your target installation ( ).

37 Old plug-in version

38 Update plug-in version Change the date on the plug-in version to today’s date and time.

39 Update plug-in version Do so for both plugins.

40 Creating an update site Task [HOW TO] Build an Update site for the RTC 3.X Client 1.Modify bundle version in the plug-in xml version number suffix. 2.Create a new feature project. 3.Add plug-ins to the feature project. 4.Create an update site project. 5.Add the feature. 6.Save and build.

41 Feature Project Create a new feature project –Make sure you are in the Plug-in Development perspective –File->New->Project

42 Feature Project

43 Feature Project Task [HOW TO] Build an Update site for the RTC 3.X Client 1.Modify bundle version in the plug-in xml version number suffix. 2.Create a new feature project. 3.Add plug-ins to the feature project. 4.Create an update site project. 5.Add the feature. 6.Save and build.

44 Select plug-ins

45 Feature Project

46 Feature Project Set the versions correctly. Versions are in Plug-ins tab.

47 Plug-ins tab

48 Update versions and save

49 Update versions and save

50 Create update site Task [HOW TO] Build an Update site for the RTC 3.X Client 1.Modify bundle version in the plug-in xml version number suffix. 2.Create a new feature project. 3.Add plug-ins to the feature project. 4.Create an update site project. 5.Add the feature. 6.Save and build.

51 Create an update site project File->New->Project –Plug-in Development Update Site Project

52 Create an update site project

53 Create an update site project Name: HotFix276616_For_RTC_Client 4.0.1

54 Update site project

55 Create update site Task [HOW TO] Build an Update site for the RTC 3.X Client 1.Modify bundle version in the plug-in xml version number suffix. 2.Create a new feature project. 3.Add plug-ins to the feature project. 4.Create an update site project. 5.Add the feature. 6.Save and build.

56 Add the feature Create a new category and add the feature project to this category –Category ID: IBMSupportPatch –Category Name: IBM Support patch for work item

57 Add the feature

58 Add the feature

59 Create update site Task [HOW TO] Build an Update site for the RTC 3.X Client 1.Modify bundle version in the plug-in xml version number suffix. 2.Create a new feature project. 3.Add plug-ins to the feature project. 4.Create an update site project. 5.Add the feature. 6.Save and build.

60 Build Build the update site –Build All button

61 Save and Build All

62 Find the update site It will be in the sandbox

63 Check the update site Verify that the version ids on the jar files are correct.

64 Check the update site The version id on the feature jar file will be qualifier

65 Test the update site Start an Eclipse client from the target release installation (4.0.1) Use a different Eclipse workspace –E.g., RTC-test Install the hot fix –Help --> Install New Software –Add the update site pointing into your sandbox

66 Test the update site

67 Test the update site

68 Test the update site

69 Test the update site

70 Test the update site

71 Test the update site

72 Test the update site

73 Verify Installation The directories or jar files in the plugins directory of the installation should show the new bundles.

74 Verify Installation

75 Verify Installation

76 Verify Installation Help->About Rational Team Concert –Installation Details -> Installed Software

77 Verify Installation Help->About Rational Team Concert –Installation Details -> Plug-ins

78 Verify Installation Test your fix in the target installation against your original work item.

79 Deliver the Hot Fix Package hot fix as a zip file Create a Readme Resolve the work item Upload to Rational Fix Portal

80 Package hot fix as a zip file HotFix276616_For_RTC_Client_4.0.1.zip

81 Create a Readme HotFix27716_ReadMe.txt

82 Readme Hot Fix : Cannot browse baselines before the latest 1024 Hot Fix Contents: Eclipse update site (archive format): HotFix276616_For_RTC_Client_4.0.1.zip Contains contains the following enhancement: : Add System property to control maximum number of baselines returned in a query in the Eclipse client - This hot fix is valid only for RTC This hot fix is not operating system dependent. - This is an RTC client-side hot fix. It only needs to be applied to RTC Eclipse clients. How to Apply the Hot Fix: 1) Unzip the hot fix "update site" from the supplied zip file into a temporary directory: /HotFix276616_For_RTC_Client_4.0.1/ 2) From the RTC Eclipse client, install the hot fix from the hot fix update site: Help -> Install New Software... -> Add->Local -> /HotFix276616_For_RTC_Client_4.0.1/ 3) Restart Eclipse

83 Readme 4) Verify the hot fix applied correctly: Help->About->Installation Details->Installed Software "Hot Fix for RTC Client 4.0.1" Help->About->Installation Details->Plug-ins IBM Jazz File System IDE Plug-in v _1745 com.ibm.team.filesystem.ide.ui ^^^^^^^^^^^^^^^ IBM Jazz File System Client Library Plug-in v _1745 com.ibm.team.filesystem.client ^^^^^^^^^^^^^^^ verify new plug-in versions 5) To use the feature, set the system property SCM_MAX_BASELINE_QUERY_RESULTS in the client eclipse.ini file, under the vmargs section. Here is an example. -DSCM_MAX_BASELINE_QUERY_RESULTS=9999 This will set the maximum number of baselines returned by a query in the Eclipse client to 9999, instead of the default 1024.

84 CLI or Server Hot Fixes CLI and Server hot fixes cannot be installed with an update site Deliver just the zipped jar files and the Readme –Export the plug-in that contains the hot fix change From the package explorer view, click export, expand the Plugin Development node, select deployable plugins and fragments..

85 Server Hot Fixes –Be sure that the plug-in names (build ids) match the target release. The plug-in version (e.g. v _1003) must match the original plug-in. You will need to rename the plug-in that is exported Example: – Original jar file: »com.ibm.team.scm.service_3.0.4.v _0348.jar –Exported jar file: »com.ibm.team.scm.service_ jar –Rename it to match the original jar file.

86 Server Hot Fixes Extra steps for server hot fixes –Add extension code to the plugin.xml file to identify the hot fix.

87 Server Hot Fix Extension Code <patch name="Fixed a problem with FOO“ productId=“ " id="com.ibm.team.support.fixWorkItemXXXXX_to_v301iFixX" buildId=" “ version="3.X.Y.Z wiXXXX"/>

88 Example (with context) <patch name="Hot Fix for defect : User without permission can unlock file” productId="com.ibm.team.rtc.web.product" id="com.ibm.team.support.fixWorkItem259824_to_v3013" buildId="v _1645" version=“ hotfix259824"/> Note that the buildId for the XML file (above) corresponds to the date and time that you created the hot fix, not the old version id that you must use for the name of the jar file.

89 Example Server Hot Fix Readme Hot Fix for defect : User without permission can unlock file =========================================================================== Hot Fix Contents: compressed Zip file containing an RTC server plug-in jar: HotFix zip Contains fix for this defect: : User without permission can unlock file - This hot fix is valid only for RTC servers. It is not valid for any other version of RTC. - This hot fix is not operating system dependent. - This is an RTC server-side hot fix. How to Apply this Hot Fix ======================== 1) Prepare your RTC server to recognize the new plug-in. With the server running, open the the following URL in a browser using account with jazzadmin privilege: : /ccm/admin/cmd/requestReset 2) Shut down the RTC server

90 Example Server Hot Fix Readme 3) Make a back-up copy of the existing plug-in being patched. Open the RTC server's CCM update site "plugins" folder: /conf/ccm/sites/rtc-commons-update-site/plugins/ and make a copy of the existing plug-in: com.ibm.team.scm.service_3.0.4.v _0348.jar.BACKUP 4) Extract the new version of the plug-in from HotFix zip into the update site "plugins" folder: com.ibm.team.scm.service_3.0.4.v _0348.jar 5) Restart the RTC server. 6) Verify the hot fix applied correctly. - Open this URL in your browser: : /ccm/admin - Click on "Status Summary" on the left side of the page - The "Build Information" section should list this hot fix: "Hot Fix for defect : User without permission can unlock file hotfix (v _1645)" plus other hot fixes (if any) that you previously applied to this server.

91 Resolve the Hot Fix Work Item Release Information Tab –Attach the zip file and the Readme –Copy Readme into the Readme File field –Set “Adopted in Release” to the release that contains the fix. For example, a hot fix on top of might be adopted in release In theory, wait for approval from L2 before uploading to Rational Fix Portal.

92 Upload to Rational Fix Portal Login with your IBM Intranet ID. Click tab “Submit A Fix/Remove A Fix” Step 1: Select a product: Rational Team Concert Step 2: Select an operation: Submit A New Fix to FTP Fix Archive File –Upload the zip file Readme –Upload the Readme Fix Description –Hot Fix : stream-snapshot compare affected by unload or folder rename (defect ) Others –Make sure (IBM) requestor of hot fix is included Fix-Type is “Test Fix”.

93 Upload to Rational Fix Portal You will get an FTP link. Add it as a comment to the Hot Fix work item. Example 9. Steven Holtsberg, Jul 31, 2013, Charles, I have uploaded the hot fix to the Rational Fix Portal. Look for the confirmation. Once it's ready, the customer can download the hot fix from here: ftp://ftp.software.ibm.com/software/rational/private/RTC-Jt0jPY18K43H Please review, as appropriate, before informing the customer of the hot fix.Steven Holtsberg ftp://ftp.software.ibm.com/software/rational/private/RTC-Jt0jPY18K43H