Are you an effective Rational Team Concert Source Control user? If you’re not sure, or simply want to become more effective, here are some essential tips that will help on your way. Before jumping in to these tips, we have some excellent resources that would be worth taking a look at:

• If you’re new to SCM’s, check out Getting Started with Jazz Source Control.
• If you have experience with other SCM’s, Easing into Jazz Source Control was made for you.
• A very handy reference for everyone is our Jazz Source Control FAQ.

1. Check-in frequently (and deliver when ready).

Have you ever had a hard drive failure or your notebook stolen? If so, didn’t you wish you had a backup available? Of course, that is one of the reasons for using Source Control. Make it a habit to frequently check-in your local changes into your repository workspace. The repository workspace belongs to you and it is safely stored in the RTC server.  You can easily reload it into a new sandbox on a different machine and get back to work.

What happens if you accept incoming changes but you haven’t checked-in your local changes? These local changes may be replaced with the ones you have accepted, and there would be no copy of your local changes in your repository workspace. That is why RTC Source Control will detect that situation and suggest you check-in before accepting. RTC does have additional safeguards (see Finding Lost Content with Rational Team Concert) because we don’t like to lose your data, but the advice is simple: check-in!

All right, we’ve explained why it’s best to check-in so your repository workspace stored on the server contains an up to date backup of your sandbox. Some first time users told us they thought that when they check-in, they also must deliver at the same time. Not at all. You deliver changes from your repository workspace to a stream when you decide these changes are worth sharing. I.e., when they are useful to others, when they are good enough – you have no compile errors, you’ve run junit tests locally or you’ve run a personal build against your repository workspace.

Learn more at Checking in unresolved changes, Choosing automatic or manual check-in for the RTC client for Eclipse IDE, Checking in automatically or manually for the RTC client for Microsoft Visual Studio IDE, Resolving conflicts, Synchronizing sandboxes.

2. Always interrupted? Suspend and resume.

You’re in the middle of implementing a new feature, and your manager passes by and says “I need you to fix bug 100 right away”. You don’t have time to explain that your environment is partly broken because you’re in the middle of some refactoring. Easy… Check-in all your local changes and suspend your outgoing change sets. You’re back to a healthy state. Fix bug 100, run your junits and deliver. Then resume your previous change sets and get back to that exciting new feature.

Learn more at Getting Started with Jazz Source Control (Suspending an Outgoing Change Set).

3. Create baselines frequently.

Sure, Source Control lets you go back in time by suspending or discarding change sets in your history. But what change sets exactly do you need to discard? That is where snapshots and baselines come into play. Whenever your stream reaches a meaningful state – green build, milestone or release, before a big merge, after a big merge – you should create a snapshot to capture the exact state of each component in that stream. Or create a baseline if you just care about your own component. Automated builds can be setup to create snapshots automatically and link to them in the build results. Snapshots and baselines make it easy to bring back your workspace or stream to a known safe point. They are also commonly used to recreate an old setup, e.g. to try to reproduce a problem that only occurs with an old version of the product.

Learn more at Multiple Stream Development (Baselines). Going back in time, Practicing source control archaeology with Rational Team Concert.

4. Doing some changes to fix a bug? Associate a work item to your change set.

Source Control and Work Items are completely integrated. When you compare two build results or look at the history of a component, you can see the change sets and the work items they relate to. So you know how files were modified and why they were modified. If a change set doesn’t look right, you can open its related work item and have a conversation with the owner of the work item. And vice-versa, work items link back to their associated change sets. All you have to do is associate the work item to the change set you create.

Learn more at Getting Started with Jazz Source Control (Different Ways to Associate Work Items with Change Sets).

5. Why is a section of the code implemented that way? Use Annotate to find out.

Some files receive many contributions from different developers. When I am in a file and am trying to understand why the code is the way that it is, one of the first things I do is to run the annotate action. It shows in the editor who last modified each line in the file. And since this is Rational Team Concert, the annotation is linked to the corresponding work item and full change set. That allows me to understand why that code was added. I can then discuss with the person who introduced the code and maintain that code better. If the code introduced a problem, I can even see from the history view when the problem was introduced.  The purpose is not to shame or blame anyone – regularly enough, it’s my own name that shows up in the annotation. Getting and giving developers feedback on the consequences of their past contributions allows us to become more experienced professionals and improve code quality. That’s another powerful way Source Control helps a team work better and get smarter over time.

Learn more at Practicing source control archaeology with Rational Team Concert (Annotated file display), Annotate (CLI), Viewing annotations (RTC client for Eclipse IDE), Viewing annotations (RTC client for Microsoft Visual Studio IDE).

6. Lock files that can’t easily be merged.

You’ve modified a file in your repository workspace, someone else in your team has modified the same file. You can accept that change and use a compare editor to merge the text changes. But what if the file isn’t text, what if it is produced by a tool that doesn’t really support merging? There’s a simple workflow for avoiding this kind of situation. Accept the latest from your stream, so you know you’ve got the latest version of that file. Then lock that file in the stream you and your team members are using to share changes. Now only you can deliver changes to that file in that stream. Your team members will see that you have locked that resource and can have a pleasant conversation with you on when you plan to be done and release your lock.

Learn more at Locking resources in the RTC client for Eclipse IDE, Locking resources in the RTC client for Microsoft Visual Studio IDE.

7. Need to work with multiple streams? Change flow target.

Sometimes a developer needs to accept (or deliver) changes from (to) different streams for different components, into their repository workspace. On the workspace, change the flow target and pick the new stream, The pending changes view now shows outgoing and incoming changes between the workspace and that new stream. Then change the flow target back to the previous stream when appropriate. Switching flow target is easy to do and it is a very convenient way to collaborate with different streams.

You can change the flow target for the whole repository workspace, or even just cherry pick some component(s) in your repository workspace. You can simultaneously have some components flowing to one stream and others to a different stream. This is very convenient when you need to continuously sync up with your team’s stream on most components, while collaborating with another stream for some other component.

Learn more at Adopting the latest changes from another team, Adopting the latest changes from multiple streams,  Stream strategies with Rational Team Concert 3.0.

8. Enforce good practices with preconditions on deliver.

Many of us have accidentally delivered change sets that were missing comment or work items, code that was missing a regulatory copyright notice. Or even delivered to the wrong stream. Source Control can help you fix these accidents afterward. But what if you could prevent them from occurring in the first place? That’s where the powerful integration between RTC Source Control and Process really shines. You can pick which preconditions to enforce on the deliver operation in your project area or team area, for everyone or specific roles. Require change sets to have a work item and/or a comment. Require a copyright notice in source files. Control who can deliver to certain components in a particularly important integration stream. If the preconditions set are not met, the developer won’t be able to deliver their changes and the team advisor will describe what is missing. The developer can correct things and deliver again.

Learn more at Team process preconditions for RTC Source Control (RTC client for Eclipse IDE), Team process preconditions for RTC Source Control (RTC client for Microsoft Visual Studio IDE).

9. Share your documents easily through the Source Control Web UI.

Source Control is integrated with the Eclipse and Microsoft Visual Studio IDEs, and the CLI. That’s great for developers, but what about managers, analysts, architects who just want to quickly peek into some document? Just point a web browser to your RTC server and navigate to the appropriate project area. In the source control menu, you can navigate into existing streams, components and their resources. You can visualize and edit text content from within the web browser. Or you can lock the resource (e.g. a spreadsheet) in that stream to prevent anyone else from modifying it, download it into your native office application and upload the new content back (and unlock). Anyone with access to that stream will see your latest version, as well as the previous ones, whether they use the Web UI or the clients for Eclipse or Microsoft Visual Studio.

Learn more at Share and manage documents through the Rational Team Concert Web UI.

10. Need to clone a repository workspace or a stream? Just do it, it’s cheap!

You’re going to do some work on some complex experimental feature and maybe other developers will need to work with you. But doing that work in the main development stream isn’t a good idea. Maybe that feature won’t make it in the current release. The solution is easy. Duplicate the stream you are starting from, give a name and appropriate description to that new stream, and start delivering your new changes to it. You can also duplicate your repository workspace as many times as you see fit. You can keep one to fix bugs in the current stream, one to work on the new feature, etc. Duplicating repository workspaces or streams is cheap. It doesn’t use much space on the server – because behind the scenes, they all quickly fall back to the exact same change history which is stored only once. So go ahead, duplicate workspaces and streams to fit your changing needs, and delete them whenever you don’t want to see them anymore. When deleting a stream, you’ll be asked to keep a snapshot around just in case you change your mind and want it back.

Learn more at How scalable are repository workspaces?, Stream strategies with Rational Team Concert 3.0.

11. A green build can automatically deliver its changes to a stream (new in 3.0.1).

Your team has a continuous build running on their stream, so they know if things look good or broken. The build definition for that continuous build can be customized and instructed to perform extra steps after a green build. Like delivering the new changes in the green build to a target stream. I will call that target stream a green stream here. Developers don’t deliver directly to that green stream, only the build machine delivers to it. This means the green stream only contains changes that were validated by a green build. A releng person can now work with confidence and accept changes from that green stream and deliver them for adoption in another integration stream. This is a powerful alternative to personal builds, with less room for user error or laziness – make the tool work for you, not the other way around.

Learn more at How to keep your streams flowing smoothly in Rational Team Concert 3.0.1.

12. You can accept and deliver changes between different servers (new in 3.0).

You’ve got RTC servers in different locations managed by different groups in your organization. What if two teams on different servers need to collaborate on a particular project? You can enable the source control distributed capability on these servers so developers will be able to flow change sets between the two servers. As a user, it is as simple as changing the flow target to a stream or workspace on a different server.

Learn more at Flow changes cross repositories with Rational Team Concert.

13. Load what you need.

In most cases, a developer will load their entire repository workspace onto their local disk – into what we call a sandbox, e.g. an eclipse workspace if you’re using the RTC client for Eclipse IDE. You can decide to load only some components. You can even load only certain folders in a component and control where they get loaded in the sandbox.

Learn more at Loading Content from a Jazz Source Control Repository in Rational Team Concert.

I hope this will help you effectively collaborate with your team through RTC Source Control. The RTC Source Control development team and the RTC teams in general use these practices and workflows every day in our Jazz self-hosting environment. There’s much more we could discuss, so drop by the RTC user forum to ask questions.

Christophe Cornu
RTC Source Control Client Lead