windows shell integration advanced

© 2016 IBM Corporation1

Sreerupa Sen STSM – Rational Team Concert

IBM Rational Team Concert - Windows Shell Integration, Advanced Mode


Outline Goals Getting started Modes of operation Usage patterns Setting up your work area Working in the Shell Code review Handling conflicts Preferences Client Parity


Who does the Shell Integration target?

Windows users who want to use Rational Team Concert (henceforth RTC) for source control, tracking and planning

Developers who use a different IDE than the ones supported out of the box (Eclipse and Microsoft Visual Studio IDE are the supported IDEs)

Such as embedded developers who often use other tools/IDEs

Non developer users such us documentation engineers, analysts, user experience designers…

Who do not need to use IDEs but would want to version control their documents and artifacts

Multiple modes of operation depending on your usage patterns


What’s the goal for this integration?

The goal is To use this integration for version control of your source artifacts, and the day-to-day

developer workflows

To use RTC browser clients for tracking and planning your project

To use RTC browser clients for managing builds

To use RTC browser clients for admin work

[Note: The admin may need to use the Eclipse client for certain tasks that have not been web enabled yet, though a lot of parity work has been done in the last few releases

Some process customizations can only be done via Eclipse though most are now via the web client

Creation of build definitions requires an Eclipse client as well]


Welcome! You’ve just installed the RTC Shell Integration and restarted your machine

The welcome screen pops up, with options to explore the tool

It asks you to choose a mode of operation: Advanced (focused on power users) or Basic (focused on others)

You can always change the mode of operation any time you’d like

You could use the “Help me choose” link for guidance

More on modes later in the presentation


How do I get started? The Shell icon shows up in the Start Menu, Task Tray and in your Desktop

The Task Tray icon has a set of menu items that can connect you to the control panel or log you in or connect you to your local work area (sandbox) that’s managed by RTC

Clicking the icon shows you the status of your RTC connections and managed work areas

In the other places, clicking on the icon takes you to the control panelDesktop

Start Menu

Task Tray

Status via Task Tray


Modes of Operation It’s not one size fits all! Advanced and Basic Modes

Advanced mode focused on power users (usually developers)

Basic mode focused on users who want a simpler, guided experience

Different usage patterns and user experience


Advanced Mode

Developer focused – rich-client-like experience Control Panel to set up RTC SCM Artifacts View for managing artifacts Advanced Preference Management Pending Changes View for fine grained control of source

control operations Rich context menus on files and folders History view to look at file history

In these charts, we’ll focus on the advanced mode


Basic Mode

Get started quickly and easily File oriented use, simple menus Don’t care about advanced RTC SCM concepts. Guidance, simpler usage patterns, verbose notifications History view to look at file history


Shell Integration at a glance The Control Panel lets you manage your connections, source control

artifacts, preferences The context menus against managed files and folders let you perform a

host of SCM operations The Pending Changes View gives you fine grained control over your SCM

artifacts and provides advanced RTC SCM functions The History View shows file history The task tray icon lets you connect to your Control Panel and your work

area, and shows your status


Shell Integration at a glance – Advanced Mode


Usage Patterns Contribute to a feature/module that your team is working on

(starts with loading a repository workspace), or

Start working on a new feature/module and share with your team (starts with sharing to a component in a repository workspace)

Once you’re set up for contribution to a new or an existing feature, you’d use the Shell integration for collaborative software development, with the same pattern of change/check-in/review/deliver/accept/merge/change…

In the next few charts, we’ll talk about setting up for share or load.


Outline Goals Getting started Modes of operation Usage patterns Setting up your work area

Contribute to an existing feature

Work on a new feature

Working in the Shell Code review Handling conflicts Preferences Client Parity


Contributing to an existing feature

Get connected to an RTC repository/project area (Shell Control Panel)

Accept a team invitation or

Create a new repository connection and connect to a project area

Create a new repository workspace from your team’s stream (Shell Control Panel)

Load the Repository Workspace into a local work area or sandbox (Shell Control Panel)



Login to a browser based RTC Client and look at your team’s plan to see what’s assigned to you this sprint (Web)

Work on the source files for the feature (any editor or your own IDE) Undo, check in, accept changes, suspend/resume changes, discard changes

(Shell Context Menus, Pending Changes View) Compare, merge (Shell Context Menus, Pending Changes View)



Associate with work items (Shell Context Menu, Pending Changes View) Submit for review (Web) Incorporate review feedback (Web, local editors) Deliver to team stream and resolve the work item (Shell Context Menu,

Pending Changes View)


Contributing to existing: Get Connected Using the team invite that you received you could connect to a

repository/project area/team area Or you could connect yourself using the Control Panel options


Contributing to existing: Create and Load a Workspace

You can create a repository workspace from stream or a snapshot that has your team’s changes

Access permissions are set to private by default but you could change the scope

Note that the visibility of change sets you create isn’t controlled by this access

You can pick and choose the components you’d like to work on

Note that for local builds to work, often times you’d need to load dependency components that you’re not directly working on.


Contributing to existing: Create and Load a Workspace

By default, a the “New Workspace” operation loads the workspace into your local machine as well

You can load based on load rules, or create additional folders while loading

The root folder that you load into becomes your sandbox or work area This is tracked by RTC from now

onwards

More on this later


Contributing to existing: Load Rules Your team may have specific load patterns expressed via load rules

Load under a specific folder hierarchy

May be different for different components

Note: Load rules can be created only via the rich clients but applied across all clients including the Shell integration

Your team lead may have shared the rules file via email with you, and it’s on your local machine – aka local load rules file

Or the load rule file may have been delivered to your team’s stream – aka remote load rules file

Either way, you can load a repository workspace to match the patterns defined in a load rule file


Contributing to existing: Local and Remote Load Rule files


Contributing to existing: next steps Once you’re set up, the rest of the experience of working in the

shell is the same as when you’re working on a new feature, and we’ll describe that in a bit, in the ‘Working in the Shell’ topic


Outline Goals

Getting started

Modes of operation

Usage patterns

Setting up your work area

Contribute to an existing feature

Work on a new feature

Working in the Shell

Code review

Handling conflicts

Preferences

Client Parity


Work on a new feature You’ve been working on a new feature in a folder in your local machine and

you’re ready to share it with your team now Set the root folder in your work area as your sandbox (Shell Context Menus) Once the sandbox is set, you can share the top level folders under the

sandbox (Shell Context Menus)

You can share into an existing component, your folder becomes a top level folder in the component

You can share into a new component

The component can be in an existing workspace or you can create a new workspace

Once shared, your source code is checked in to the RTC repository

Note: The share workflow in the Shell by default prompts you to deliver your changes, but in non-trivial cases you may want to get your changes reviewed first


Work on a new feature Associate your changes with work items (Shell Context Menu,

Pending Changes View) Submit for review (Web) Incorporate review feedback (Web, local Editors) Deliver your changes to your team’s stream (Shell Context Menus,

Pending Changes View) If you’ve created and delivered a new component, it will show up

as an added component in your team’s stream that your team members will need to accept (Pending Changes View)

Note that in this case, you didn’t need to explicitly get connected to RTC. If you’re not connected, the Share operation prompts you to get connected


Work on new feature: Set Sandbox Once you set a sandbox, RTC

starts managing the files and folders under the sandbox

A .jazz5 folders stores the RTC metadata

While setting a sandbox, you could at the same time load a repository workspace into the sandbox

If a repository workspace is loaded, your new changes would typically be shared into a new or existing component in that repository workspace

Useful when you’re adding a new feature to a set of existing features

Otherwise you make your choices for repository workspace/component during Share


Work on new feature : Share

The Share workflow is comprehensive If you’re not already connected,

you can connect to a new RTC repository

You can create a new repository workspace or use an existing one

You can create a new component or use an existing one

all as a part of the Share workflow


Work on new feature: Share The Shell integration also

prompts you to deliver as a part of your Share workflow If you’ve selected a workspace,

your changes will be delivered to the default flow target for the repository workspace

If you want your changes reviewed before you deliver, do not deliver your changes as a part of Share. Instead, associate your changes with a work item and submit for a code review

Once delivered, your team can see your changes


Work on new feature: next steps Once you’re set up, the rest of the experience of working in the shell is the

same as when you’re contributing to an existing feature, and we’ll describe that now, in the ‘Working in the Shell’ topic


Outline Goals

Getting started

Modes of operation

Usage patterns



The Sandbox

Working with files

The Pending Changes view

Code review

Handling conflicts

Preferences

Client Parity


The Sandbox: what is it? This is your work area, the root

folder, under which

you load your repository workspace,

or have folders which you share with your team

It shows up in the list of sandboxes in the Managed Artifacts view

Easy access from the task tray icon

Any SCM operation with files and folders requires a sandbox to be set


The Sandbox: multiple sandboxes and switching

You can only track one sandbox at a time with the Shell Client

You can switch to a new sandbox either via the task tray context menu or the Artifacts View

You can switch between existing sandboxes via Open Sandbox in the task tray or the ‘Set Current’ option on a sandbox in the Artifacts View

All the meta data for all the sandboxes are preserved across switches

The idea is that you work on one sandbox at a specific point in time, and switch back and forth if you need to

We could have supported multiple sandboxes at one time, but some of our richer integrations like the Pending Changes View would become complex to use


The Sandbox: files and folders You can perform RTC SCM

operations on files and folders in the sandbox

They have RTC context menus showing up against them

Files and folders in the sandbox may have state specific glyphs showing up against them

Glyphs for unresolved, shared, outgoing, incoming, conflict, …

Note: The total number of glyphs that Microsoft Windows allows is restricted, so if you have other tools that set glyphs, the RTC glyphs may or may not show up


The Sandbox: Pending Changes View Changes to your

sandbox are tracked in the Pending Changes View

More on that later


Outline Goals

Getting started

Modes of operation

Usage patterns



The Sandbox

Working with files


Code review

Handling conflicts

Preferences

Client Parity


Working with files in the Sandbox You could use the context menu options on the tracked files and folders

Change set management will be done by RTC under the hood

Good enough for the simple workflow• Make changes to one or more files• Check in to a change set.• Associate one or more work items with your changes (optional, but recommended)• Submit for review • Incorporate review feedback• Deliver.

– Note that if you multi-selected files during check in, they’re all part of a single change set, so Deliver will deliver all the files even if you’ve selected just the one.

– If you haven’t associated a work item yet, based on your preferences, Deliver can prompt you to associate a work item as a part of the workflow.

– You could also directly choose to deliver the files that you changed. It will check in the files, prompt you for a comment and a work item (based on preferences) and then deliver the changes.


Working with files in the Sandbox


Status of a File in the Sandbox Overlays show status

The Windows Explorer has a limitation on the number of overlays that can be shown on files and folders

What other tools in your system impacts the overlays that you see.

Status may or may not show reliably

The Pending Changes Status menu option shows status

More reliable


File Properties The Jazz section in the

Properties View has the RTC related properties for a file.

You can change the executable property, or the line delimiter or MIME type for your platform if you’d like. The line delimiter/MIME type is

used by the compare tool

You can also define custom properties


History View ‘Show History’, invoked from the context menu on a file in the sandbox,

shows the version history of a file.


Outline Goals

Getting started

Modes of operation

Usage patterns



The Sandbox

Working with files


Code review

Handling conflicts

Preferences

Client Parity


Working in the Pending Changes View Lets you work with files

and change sets Undo, check-in, deliver,

accept, associate with work item

Advanced uses Suspend and resume: I want

to work on this critical customer defect, so suspend my current changes for now, I’ll resume them later from my workspace

Discard: not interested in these changes any more


Working in the Pending Changes View Advanced uses

Setting flow rules • I want to back-

port this change to a maintenance stream

• I want to both accept changes from and deliver changes to my team’s stream, and only deliver changes to the integration stream


Working in the Pending Changes View: Submission for Code Review Advanced uses

I want to submit my changes for a peer review before I deliver• ‘Submission For Review’

completes the change set, associates a work item and adds an approver, all in the same workflow

• You can associate an existing work item or create a new one

• Integrated with the new Code Review feature in 6.0.1


Working in the Pending Changes View: Submission For Code Review


Reviewing Code: 6.0 and earlier

Prior to 6.0.1 Reviewers could view the

change sets submitted for review in the browser based client

Add review comments to the associated work item

Or they could review change sets via the Change Summary View in one of the rich clients


Reviewing Code: 6.0.1 Your project admin needs to set up Code Review for your project (more on

this later) Now when you submit for Code Review, the review information gets added

to the Approvals tab Click on the Open Code Review button to start the review in the browser


Reviewing Code: 6.0.1


Code Reviews in 6.0.1: Set up To enable the new code review feature in 6.0.1, your admin needs to set it up via the

project area editor in a browser client

Your project admin needs to add an approval attribute for Code Review for code review to be enabled in your project.

Since 6.0.1


Handling Conflicts If you and someone else

are working on the same file and s/he delivers first, you may get a conflict when you accept incoming changes

If your changes are checked in, then you get a conflict

If your changes are still local (Unresolved) then RTC will warn you that it may overwrite some changes. Do not ignore the warning unless you don’t care about your changes


Handling Conflicts You could try to auto-

resolve, RTC will prompt you if it’s unable to.

Use the compare merge editor to resolve conflicts manually

Resolve with mine overrides the incoming changes

Resolve with proposed overrides your changes


Preferences

Customize your workflows via preferences

Use a compare tool of your choice plugged into the RTC compare merge process

Export your preferences to a file and share with your team or import your team’s preferences into your environment


Does this integration give me all SCM functions I get in Eclipse or Visual Studio Clients?

This integration is focused on developer work flows Team workflows such as creation of streams needs to be done

via a rich client.

This was intentional; the shell client is supposed to be lightweight the goal was not to make it clunky

Developer workflows such as creating and loading workspaces, sharing your files and folders and related activities are the focus


Does this integration give me all SCM functions I get in Eclipse or Visual Studio Clients?

IDEs support editors and views, the Windows Explorer does not We wanted the integration look and feel as shell-native as

possible

Some views such as the Pending Changes View and the History View are an important part of the developer workflow, and can be used in the Shell

We could have implemented all editors and views in the Shell but then it would look like a rich client embedded in the Shell, or a standalone tool

Your feedback is welcome!


Backup


Install Tips During uninstall/install, instead of restarting your machine, you could kill the shell

process (explorer) in the task view, uninstall, reinstall and then restart it in the task view again (File->New Task(Run…))

The Shell installer lets you choose if you want to restart after an install/uninstall

If you don’t restart, you may see unexpected behavior in your Windows Explorer


Thank you!

windows shell integration advanced

Software