handling source files for multiple versions

[ndhelp]

Ok, I've looked around on the web and multiple discussions and have yet to find an answer. We currently have two authors working on the same help project that we have handled relatively successfully under RoboSource. Our development environment has changed so that we need to be able to support multiple versions of the help at once ie- release branch vs development branch that we want documented but it is not yet slated to be in the release.

I've looked at the help for RoboSource and there is an idea of branching but not much help on how this is done or if it really maintains two sets of the files, etc. I've also seen some postings on the forum for this that have gone unanswered. Makes me suspect that perhaps RoboSource doesn't really support multiple versions of help source files. I would be happy to admit that I'm wrong here.

Another option to solve our challenge is by committing our source files to the development source system, SVN. I've noticed some threads discussing this. I'm unsure from reading these posts if RoboHelp alerts you when you are about to modify a file, such fpj or hhk, that is being used by someone else like RoboSource does. Since we still have two authors playing in the same help project it would be most efficient if it would notify us before letting us write over one another's work.

Can anyone shed some light on:

1) does RoboSource really support multiple versions of the help source files and how it is done?

2) does RoboHelp notice when a file is locked in SVN and notify the other author to keep hands off until it is committed again?

3) is there somewhere better for me to research this?

Thanks you for any assistance you can provide,

Nita

[RoboColum_n_]

We don't use RSC here so I can't really help you there apart from offering that it works in a similar way to Visual Source Safe. My understanding is that you'd have to have two different versions of the source (one per version) and maintain both side by side.

We are experimenting here with SVN on a small project. We are still in the middle of the test but as far as I can see (I'm not really involved in the test) it will allow for branching but does not inform you if another author is working on a file UNTIL you go to check in. Only then will it notify you. When the other person checks in , they then get a message that the source has changed since they got the source and have to follow a merge process to combine both sets of changes.

Personally I am rather sceptical of this method of source control. In a development environment this may be less of an issue but with RH projects with their project structure, things get a little more complicated. Say both authors are adding/deleting topics, amending topic file names, adding index keywords, amending the TOC, adding mapids, maintaining baggage files, etc. then all sorts of underlying files are being changed. Whilst it is possible to merge all these changes it is a process that is open to mistakes and is far more time consuming that with other source control applications. Just my two penneth!

---

Read the RoboColum(n).

[ndhelp]

Thanks Colum. I was suspecting this behavior myself. I believe with MergeThis's instructions I can continue to keep my projects in RoboSource. It plays much nicer with RoboHelp files even with it's few gliches.

[MergeThis]

We're using RSC 3.1 with RH 8 and with RH X5, and we've found that this is actually a two-step process:

1. Branching is the method for copying a snapshot of a folder (to establish two branches of the same source).
2. Reconciling (AKA forward/back patching) is the method for synchronizing edits between branches (or not, as the case may be).

For example, a "V12.3" branch of the "main" source has been prepared for one customer's specific needs. All edits to "main" will be forward patched to "V12.3," but edits to specific areas of "V12.3" will not be back patched to "main."

Tim, my boss, prepared the tutorials below, as much for himself as for us, and I have only stripped the screenshots to protect our intellectual property. Note also that we reference two publish locations, one for internal reviewing, and one for Release Engineering to include in our nightly product builds. Your environment might only have a single publish destination. Note also that the output files are never added to RSC.

Pay special attention to your folder naming process before you start, by anticipating any potential future branching needs. Folder renaming after the fact can be problematic in RH and RSC.

Good luck,

Leon

===================================

Branching Projects in RoboSource 3.1

Since the Help for RoboSource and Robohelp lack a proper explanation for branching and updating configuration files to support proper branching, this document has been created to assist in creating future branches.

Creating New Local Directories

Individuals must create new local path directories on their systems. We use the following conventions:

          Ex. C:\902_imsmerge\projects (source folder)

          Ex. C:\902_imsgenerate\mergedProjects (output folder)

Create New Server Directories

New server directories need to be created in two locations for holding the output files.

• One is for the Robohelp output that gets put in the nightly .war file and checked into Perforce.
• The other is in the wwwroot of our IIS server for our doc web site.

They are defined as follows:

• \\docsql01\Documentation\RoboHelp\9.0.3\imsgenerate
• \\docsql01\Inetpub\wwwroot\help_sys\9.0.3

Create new directories with the correct branch number.

Using RoboSource View Manager to Create a Branch

You use the View Manager to create a new branch. In RoboSource 3.1, a branch is just a different type of view.

1. Assume the version_903 branch has already been created. To create a new branch, click the Create button and name the new branch (version_910), leaving a blank root folder.
2. Click on Set Root to define the root folder for the new branch.
3. Select the root for the branch and click OK.
4. Select the view (branch) and click Properties. In the Properties window, select Branch as the Type, then click Close.
5. In the View Manager, check the check box to enable the view.

Setting the Local Path for the New Branch

1. Select the new branch and right-click.
2. Type in or browse to the correct local path, check the Apply Recursively box, click Apply. Close the Properties window.

Editing .xpj Files

The .xpj files in the new branch need to be edited to point to the new branch. THIS IS VERY IMPORTANT. IF NOT DONE ROBOHELP WILL CHECK IN CHANGES TO BOTH THE BRANCH AND THE ROOT.

One line in each project’s .xpj needs to change. See below.

This value must match the branch the project lives in. In our above new branch example this would be changes to %version_910.

In a merged project, you can change all these at once with the FAR tool.

Edit the .ssl and .sss files

These files need to be edited to redefine the generating and publishing paths. Note that this can also be accomplished with the FAR tool, or by having each writer do it through the GUI.

ssl Files

The .ssl files contain the data for the generate path. Although there might be seven .ssl files for each project, you only need to edit the ones for your Primary Layout and one or two others that you might also use.

Make sure the generate path is defined correctly.

sss Files

The .sss file defines the publishing paths. This edit can also be done through the GUI if necessary.

====================================

Forward and Back Patching in RoboSource

This document describes the procedure of forward or back patching files (.htm or .gif) between branches in the RoboSource system. The RoboSource product uses a feature called Reconcile Changes to accomplish patching between branches.

Example Scenario

Throughout this document we will use a real life example from the refwindows project.

• We have edited the version 9.0.3 security_master_folder.htm file in RoboHelp.
• Now, we need to backpatch it to version 9.0.2.

Selecting Folders or Files to Reconcile

You can select either:

• A single file for reconciliation
• The source folder, or
• The destination folder

If you have just one file to reconcile, you will probably want to use the single file method. If you have several files to reconcile, you will need to use the folder method.

Working from the Source Folder

Select the source folder (folder that contains the updated file) in source control. In our case, %version_903/refwindows.

1. Select Reconcile Changes … from the Action menu. This opens the Reconcile window.
2. Select the appropriate option in the Reconcile window.

In our example we select the first option to reconcile from %version_903 because that is where our updated file is. Make sure the correct project is selected in the drop-down list. ($/version_902/refwindows).

Other Options

• Reconcile changes made in another branch *into %verison_903/refwindows. This is the option you would use if you have an updated file in another branch that you want to put in 903.
• Reconcile changes made locally (in c:\903_imsmerge\projects\refwindows) and %version_903/refwindows. We would most likely never use this option.
• Reconcile changes made in another database *into* this database. Do not use.
• None of the above, let me select what to Reconcile. This one sounds like it would be a good option, but it gets even more complicated.
• Wildcard Filter. Use this to display only certain file types. For example, *.htm;*.gif;*.jpg would filter on those file types.

3. Click OK to open the Difference Reconciliator window.

Notice that this window shows all files in the project that have differences such as the .ssl and .xpj files.

IMPORTANT: NEVER reconcile these files, they are supposed to be different.

You can prevent these files from displaying by using the Wildcard Filter discussed above.

4. Select the appropriate file (security_master_folder.htm). This window will allow you to replace the file in the version_902 project unfortunately, it will also allow you to replace the updated file with the older one. Be Careful Here.
   
   You can also View Differences from this window by clicking the View Differences link.
   
   
   
5. Click the Replace button in the $/version_902 pane.
   
   You will get a confirmation dialog. Before clicking OK, take the time to read the question. This is your opportunity to catch potential mistakes!
   
   You will then get the Reconcile Checkout dialog.
   
   Be sure Perform the action directly on the Server is checked, click OK.

You see that the Difference Reconciliator window now indicates No changes to merge from %version_903/rewindows/security_master_folder.htm in the $version_902 pane.

Close the window.

Check the Destination Folder

In the source control window go to the destination branch and check the project. You can see in this shot that the security_master_folder.htm file now shows the date it was replaced, and that the server version is now different from your local version.

Working from the Destination Folder

If you had chosen the destination folder and select Reconcile Changes, the same window would have opened but with different options.

Here you would have selected the second option to reconcile into $/version_902.

You can do it either way, just pay careful attention to the options. The rest of the process is the same.

[ndhelp]

Leon,

This is truly more than I could hope for. I fought with RoboSource all yesterday and started to discover a few of these items for myself but had a long way to go. Thank you so much for replying to my post and thank Tim for working this out and writing it down. I believe this will save countless hours, if not days, of fighting to figure this out on my own. I'm off to use work through these instructions and modify for our specific environment.

Thanks again,

Nita

[MergeThis]

No problem.

Please be sure to provide feedback here, if you find any area that might need further fleshing out or is just plain wrong.

Good luck,

Leon

[ndhelp]

Leon,

The one area I found missing in the instructions was how to get the files into the newly created server directory. I created the server directories in RoboSource by creating a New Folder but I didn't find any way to copy files from one folder to another. I made a guess that worked but I'm not sure it is the most efficient.

I perfomred a Get on the files from the original server directory (say trunk or previous release) and put them into the newly created local directory (new_release). I then removed write protection from all the files and edited the xpj file in the local directory. Finally, I checked the project into the newly created branch in RoboSource. This seemed a little kludgy but it seemed to work OK.

If I'm totally off base on this approach I would appreciate an update.

Thanks again,

Nita

[MergeThis]

The newly created server directories are for output files only, and are really ancillary to the RSC branching.

You either copy output to them, or generate/publish with the new settings (.xpj, .ssl, .sss files).

[ndhelp]

I think I have a basic misunderstanding of branching then. You do not make an additional copy of your source help files in RoboSource? Where are the changes actually stored then?

We put our published files in Subversion as a zipped file in the case of WebHelp or a .chm for projects with compiled help so our published files are not a issue for us.

Our issue is keeping the changes in a main branch separate from possible release branches that do not yet have the functionality being released.

[MergeThis]

That's correct; you "do not make an additional copy of your source help files in RoboSource." The branch is causing RSC to create a "mirror image" *within its own database,* and is technically not "stored" anywhere that you can see.

Think of it as RSC creating a series of pointers that look to the "main" version, and that can be synched with "main" if and when you choose.

Also, your method of publishing obviates the need for that discussion in the tutorial I provided (i.e., creating new server directories, and editing the .sss files).

[ndhelp]

Ok, now I think I get the concept but still struggling to make it work.

So, you have a main location of the source files and you create views that use that main location as their root. If a change is made in the main area, it shows up in the views as having been changed and I found the way to incorporate that change into the view.

I'm still trying to figure out how to make a change to a view that is NOT incorporated into the main source files. Is that possible? I tried to check out from a view, edit the xpj file, make a change to a file within RoboHelp and check back in. However, my change went into my main directory and not the view.

Thanks,

Nita

[MergeThis]

Did you maybe skip the section "Setting the Local Path for the New Branch"?

[ndhelp]

That was it! This proves we can branch in RoboSource and can avoid trying to check our source into Subversion. Now to establish the procedures around it all. Have a great day and thanks again for the assistance.