Handling source files for multiple versions

Question

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

Answer 1

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:
Branching is the method for copying a snapshot of a folder (to establish two branches of the same source).
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.
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.
Click on Set Root to define the root folder for the new branch.
Select the root for the branch and click OK.
Select the view (branch) and click Properties. In the Properties window, select Branch as the Type, then click Close.
In the View Manager, check the check box to enable the view.
Setting the Local Path for the New Branch
Select the new branch and right-click.
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.
Select Reconcile Changes … from the Action menu. This opens the Reconcile window.
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.
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.
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.
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.