Polarion Software Weblog

On February 1, 2008 Polarion Software will launch our Subversion and ALM workshops in the United Kingdom (more below). Those customers and friends who started out with one of these workshops in Germany or elsewhere - now is your chance to pass along a juicy tidbit of news to your British colleagues and contacts (and we’ll appreciate it very much if you will!)

The first round is in London, and will be run by Ian Forsythe, who heads up our new U.K. division Polarion Software UK Ltd. Ian reports that the SVN workshop is almost full, so don’t wait to sign up for that one. (If you miss it, don’t worry. Ian plans to run the workshops every 6 weeks or so. Stay tuned here or to the RSS feed for announcements.)

Details and sign-up for the SVN workshop are on our site at: www.polarion.com/company/events/subv_workshop_en.php.

Same info for the ALM workshop is at:
www.polarion.com/company/events/alm_workshop_uk.php.

Cost of each workshop is £79 GBP per person. Hope to see you in London for this one, or at one of the future events in the U.K.

Sometimes people ask me how it is possible to track status of items that have been refined by subitems. Imagine having a change request that has been broken down into several tasks. In the following blog I want to take a deeper look on how parent items can be tracked even if they have been refined into subitems.

Where Planning Information is Visible

Each workitem in Polarion contains a field that represents automatically calculated planning information. This field is called planned to. It contains the start and end date to which a workitem was scheduled by Polarion during the latest planning round (update of liveplan). The planned to field is not editable and it will only be updated if the workitem is considered as an element that must be planned (please refer to the planning.xml file for more information).

As soon as Polarion has finished a planning round you will see a start and end date inside the planned to field.

How is the planned to field calculated ?

Please have a look at the other blogs on planning and linking to get a better understanding of Polarion’s planning algorithm. Today we want to analyze the parent/child relationship in more detail. Let’s take following scenario:

Our project has received a change request (EDEMO-1: “Text should be easier to read”) which has as remaining estimate of 10 days and was scheduled to timepoint Rel-1.

After a while our change request has been refined by two subtasks (EDEMO-2: “Increase text size” and EDEMO-3: “Increase contrast and color (black and white)” ) EDEMO-2 has remaining estimate of 6 days and EDEMO-3 has a remaining estimate of 7 days

Parent Items are not Visualized in Liveplan

As a matter of fact we have created a little conflict here. The child items have in sum a different estimate compared to the parent item - 13 days for the child tasks compared to 10 days initially planned for the change request. Polarion’s liveplan will manage such conflicts in following way. Parent items will be removed from liveplan when they have child items. Only child items will be visible. The reason is that remaining time estimates on child items are considered more accurate as estimates on parent items.

How Planning Information is Delegated to Parent Items

So how can we track our change request when it is not anymore displayed in liveplan and how is the conflict resolved?

Even if parent items are not visible in liveplan the planned to field is updated correctly. After Polarion’s next planning round the liveplan will contain a range of 13 days (EDEMO-2 + EDEMO-3) instead of 10 days. Polarion sums up remaining estimates of all child items and presents the result inside the planned to field of the parent item

Where Can I See Planning Information of Parent Items

If you want to see if parent items are delayed you can switch to one of the following views:

• table view,
• tree view or
• roadmap view.

You should make sure that the timePoint, plannedStart and plannedEnd columns are displayed. If an item is delayed it will be marked in red. If you want to check why an item is delayed you can change to tree view and analyze state and estimations of the child items. In our example the 13 days for change request EDEMO-1 is too long and timepoint Rel-1 can not be reached. Additionally we see that task EDEMO-2 can not be finished in time.

Best Wishes
Tim

In the last blogs we spent quite some time to discuss how you plan items and how you can react on changes in your plan. However we did not use links in our plan. As many items have relationships it is important to understand what impact these relationships can have on your plan.

In Polarion we can find three categories of links; dependency links, parent links, information links.

Dependency Links (depends on)

As already mentioned in our previous blog you should use this type of link if you want to express that one item can only start when the other item has been finished. Typically you will have that type of relationship between tasks. The link should always point from a task to the task it depends on.

Lets have a look at our plan before we will create a dependency relationship.

In this example we will assume that work on “feature 4” can’t start before “feature 1” has been finished. Currently our plan does not reflect that constraint. To achieve this behaviour we have to create a dependency link from “feature 4” to “feature 1”. We edit “feature 4” and add in the field linked workitems “feature 1”. As relationship we select “depends on”. As long as the change is not submitted you will see the workitem id in the title section. After submittion the title will be displayed in the linked workitems section.

We will manually update the plan to see what has changed. As expected “feature 4” has moved now a bit to the right as it has to wait for “feature 2” to be finished. Unfortunately “feature 4” is now also in delay due to the shift by the created dependency

As you can see dependencies are a valuable instrument to adjust and refine your plans. Knowing this people tend to make extensive use of dependency links even if no real “depends on” relationship exist between the items. They use the link more to influence the order in which the items are planned. Don’t do this - use priorities instead

Parent Links (parent, implements)

Imagine estimated a feature with an effort of 10 days. To get a better understanding of the feature the assignee breaks id down to two subfeatures: “feature 4a” and “feature 4b”. After refining the feature and describing it in more detail you add new estimates to “feature 4a” and “feaeture 4b”. No imagine that you estimate for “feature 4a” an estimate of 6 days and to “feature 4b” an estimate of 8 days. We have created a conflict in our plan. The high level feature has been estimated with a different value than its refinement.

Whenever you use parent links polarion will plan the child items and not the parent item. That means that in our liveplan we will from that point on only see the child items.

As you can see the liveplan always displays the highest refinement level. Probably you ask yourself now what happens with the estimates of the parent workitem and where can you control the status of the parent element? Whenever we want to have a view on the high level items we can consult the roadmap view which contains all items from a timepoint that you select. Personally I prefer an adjusted treeview in which I can also see why an item is in delay and what child item coused the delay.

In our example “feature 4a” is in delay and therefore “feature 4” is in delay. If the entry in the timePoint column is in red color it is in delay. “Feature 4” can only be finished at 24^th of April which is exactly 4 days later than initially planned.

Information Links (relates to, duplicates, reveals)

Information links are the easiest links related to planning as they have no impact at all. You can create as many information links as you like, they will have not change your plan. Inks are anyhow helpful to describe that some items have relationships to each other that should be taken in account. Examples are: A bug is related to a feature, a testcase reveals a bug, a change request duplicates a change request that exists already in the system.

Best Wishes
Tim

In Part 1, we worked out how you access your documents located in a Subversion repository.
In this part we will discuss several ideas how you could expose Subversion meta data, like version information, (last) author, date and so on in your document.
Currently, it is very annoying always to update version number. Most time it will be forgotten and the document is being published to third parties with wrong version number leading to confusion. Let Subversion take care on document properties.

We have two possibilities to expose Subversion information, direct and via Microsoft Office document properties and field operators.

“Direct” Exposure

This method is pretty straight forward. Just type in somewhere in your document following placeholders:

$Author:: $
$Rev:: $
$Date:: $

You can put one these entries in any place, header page or page header and/or footer are usual locations. By entering blanks between the double colon “::” and the last “$” you reserve space even in the binary formats of Microsoft Office.
After committing you document back into server, Subversion replaces each time the placeholders and it looks like this:

$Author:: neherr $
$Rev:: 150 $
$Date:: 2007-09-26 07:52:07 +0200 (Wed, 26 Sep 2007)$

It does not look nice but it is useful. If you like to reformat this ugly information after an update, you need to throw an eye on the next method for Subversion meta data exposure.

Hint Experienced Subversion users should not play with plain placeholders you normally use in text files, like “$Rev$”, i.e. without blanks to preserve space for Subversion data. After a commit your document is scrambled and you cannot read nor open it anymore.

Exposure through Microsoft Office Fields

Before we can use fields, we define document properties which Subversion updates with each commit.
Open Microsoft Office document properties dialog as shown on the right side.

I added the screen-shot for proud owners of the new Microsoft Office 2007. In the first weeks, most time spending not with writing documents but to search features and functions known from former versions but moved (hidden?) to new locations. You click on this round Office symbol on the top left corner and you will find the properties under the topic “Prepare”.

A big bar above of your document opens. Click on the “I” info button and select “Advanced Properties…”.

Owners of the “old” versions just open the “Properties” to be found in the “File…” menu.

Finally, finally, we landed in the right dialogue to define our properties.

Click on the “Summary” tab and enter the Subversion placeholder for author as shown, if the document author should be maintained by Subversion here.
Please be aware that Subversion’s understanding of author is the person who updated the document most recently.

Next click on “Custom” tab and enter two new custom properties. Please have a look on the screen-shot on the right hand side.

The name you enter is up to you. Define type as “Text” and in value you enter the Subversion placeholder as described in first section of this blog.

With the following step we are using fields to show Subversion meta data information in our document.
Click somewhere in your document where you like to show Subversion meta data and enter <Ctrl>F9. A pair of bracket appears. Enter following between the two brackets:
My first SVN property shown in my document: { DOCPROPERTY Author \# MERGEFORMAT }.
Now the second follows: { DOCPROPERTY SVNRevision \# MERGEFORMAT }.

Now the third one: { DOCPROPERTY SVNLastUpdate \# MERGEFORMAT }.
…

The string after the “DOCPROPERTY” corresponds with the name of your custom property you entered above.
After you checked in your document select the entire document by pressing <Ctrl>A, et violà.

Instead of the field definition you see the field content, like this:

My first SVN property shown in my document: $author:: neherr $.
Now the second follows: Revision: $Rev:: 151 $.

Now the third one: Last change date: $Date:: 2007-09-26 23:01:48 +0200 (Wed, 26 Sep 2007#$.
…

Due to the fact that the data exposed in both methods looks pretty ugly, macros could be triggered to cleanup and format Subversion revision information.
For this purpose it is much better to check out blogs on Microsoft’s web site.

Best Wishes
Robert

Prerequisites

• Good knowledge about Microsoft Windows and Windows Explorer
• Intermediate to good knowledge about Microsoft Office
• Access to an existing Subversion server instance with Autoversioning Commit enabled
• Optional: TortoiseSVN has been installed on your computer

General

Subversion is the perfect storage for Microsoft Office documents

• Accessing your storage runs either through http (https) or through nice Windows Explorer extension TortoiseSVN
• Binary formats are handled very well and efficiently
• Triggers released by your activities on Subversion allow defined and controlled way to disseminate information about changes
• Each document or the folder containing these documents keeps arbitrary number of properties to store meta data about your document
• Version numbers of your document could be projected directly into your document

In the subsequent blogs we will have a look on each of these topics more in detail.
With this blog we have a look how you work with Microsoft Office and Subversion.

Accessing Your Subversion Instance

“Straight”

This way to work with documents located in a Subversion repository is the easiest one you can imagine.
Just drop a URL into the open file dialogue which starts with “http://…” pointing you directly to a document in Subversion and start your work.
Each save will generate a new revision in Subversion. Please use this option sparsely especially if you are working in a network where bandwidth is a valuable resource.

Check In/Out

By using TortoiseSVN you keep local copies on your desktop or laptop computer. If you are often offline or prefer workplaces outside office, this is your choice. Before you start please ask your project manager or system administrator for URL of your project.

Also make sure that you have installed TortoiseSVN on your computer. You can check this briefly by right clicking in the Microsoft Windows’ Desktop. See context menu on the right hand side highlighting the two menu entries to check presence of TortoiseSVN.

Now browse to a folder where you like to put your documents into downloaded from your Subversion server and right-click on the folder which should be empty. Select “SVN Checkout…” and enter rhe URL provided by your system administrator or project manager identifying the location of your documents in the Subversion repository. Now Subversion uploads all data into the selected destination on your local hard disc and you are ready to start your work.

Preparing Your Documents for Exposure of Subversion

Select all your documents in your local workspace. Right-click and select “Properties” in the bottom of the context menu. Select the “Subversion” tab. Now you see a lot of data related to Subversion. For the moment we are only interested in the button in the bottom labeled “Properties”. That is next stop of our journey. Click on it and you see a dialogue which let you add some meta data for your document.

With the help of this dialogue box we add Subversion meta data to selected documents. This could be any kind of tag/value combination.

Subversion itself uses special keywords which let you influence Subversion’s behavior on the server or locally. If your organization is considering Subversion as document repository use these Subversion properties to store additional data which should not be kept in the document itself. In a later blog we will show to expose such kind arbitrary data in your Microsoft Office documents.

Now let us move on and prepare us for the next part of this blog.

In the properties dialogue click on “Add…” button opening a windows which let you add your tag/value keys. TortoiseSVN offers some of the special keywords in the drop-down menu. Please select “svn:keywords”, that is the name of the property.

Now enter the property value as shown in the screen-shot, “Date Revision Author”. The sequence of these keywords is irrelevant.
Confirm and close all dialogues by pressing OK.

In the subsequent step you will learn how to write your changes back into the server. Another time you right-click on your working directory or if you like on single files and select the menu item “Commit…”.

Commit writes all changes back to the Subversion repository. If the transaction could not be performed Subversion’s repository reverts the full transaction and does not keep the server in an unpredictable state.

A successful commit will be acknowledged by Subversion by returning a “Revision” number. This revision number let you identify the status of your data in the timeline of your work.

Numbers like this are pretty hard to remember. Subversion also allows attaching a message to each commit. This is your log or audit trail to review changes.

The upcoming dialogue shows status information during data transmission back the server. If the transaction succeeds, you will see message similar to the one in the screen-shot

.

Now stay tuned for the next part in this blog series when we pull in the Subversion revision meta data, like author, revision number, commit message or date into the document each time when we commit our changes.

Best Wishes
Robert