Using MadCap Flare with Perforce – Summary

Flare doesn’t provide support for Perforce directly, but via the Microsoft SCC API. The consequence is that Flare has a less robust and more problematic relationship with Perforce than it has with the source control systems that it supports directly (Microsoft Visual SourceSafe, Microsoft Team Foundation Server, and Apache Subversion). But MadCap Flare can be made to work quite sweetly with Perforce and I’ve written a series of posts explaining how I use them together.

First of all, don’t even try this if you aren’t using Flare 9.1 or later. MadCap have made significant improvements in this area, and there are many additional pitfalls when using Perforce with earlier versions of Flare. I’ve been battling with Flare and Perforce since Flare 7, and it’s only since the release of Flare 9.1 that Flare and Perforce can be said to work well together.

So here’s what I do.

Firstly, I bind my Flare project to Perforce. This means that as I update Flare files, they are automatically checked out of Perforce. This isn’t essential, but I think it gives you more visibility of your Perforce changes and helps you to follow good working practices, especially if, like me, you often work on several different sets of changes concurrently.

Flare contains many temporary files and output files that don’t need to be in Perforce, so I use Perforce ignore lists to tell Perforce which files not to put under source control.

Here’s how I work with Flare projects that are bound to Perforce. Most day-to-day operations (check-outs and check-ins, adding new files, deleting files) are quite simple once you work out the best way of doing them. I’ve written a separate post explaining how I move and rename files, as that’s a bit more complicated.

That’s really all there is to it. I’m not claiming this is the very best way to work with Flare and Perforce, nor the only way, but it works for me. I hope it helps you.

© Marjorie Jones February 2014

Moving and renaming files in Flare projects bound to Perforce

Introduction

This post is the third in my series about working on Flare projects that are bound to Perforce source control. It explains how to move and rename files in your Flare project. Previous posts explain how to bind your Flare project to Perforce and how to work with Flare projects that are bound to Perforce.

Before I go any further, I must say an enormous and heart-felt “Thank You” to Thomas Bro-Rasmussen, who very generously wrote a short paper on how he uses Perforce with Flare, in response to queries from several of us on a LinkedIn thread about Flare and Perforce. Without his input, this post would be far, far more complicated. It was going to start by suggesting that you found yourself somewhere quiet and free from distractions, read through all the instructions, then worked through them carefully one step at a time. Thanks to Thomas, these extreme authoring techniques aren’t necessary any more, and my instructions are quite simple after all.

Prerequisites

As before, you do need a basic understanding of Perforce, as we will be carrying out some operations directly in Perforce rather than Flare. I’m assuming you’re familiar with the concepts of checking in and checking out files, and the Perforce depot, workspaces and changelists. I’m also assuming you are using the Perforce Windows client, P4V.

Thomas states that there are known issues with some versions of Perforce, and recommends that you use Perforce Visual Client 2011.1/373647, as he knows this works as required. I have used Perforce Visual Client/NTX86/2011.1/405081, and have just upgraded to Perforce Visual Client/NTX64/2013.4/760166, and I have had no problems so far.

To follow these instructions, you need to be work in a Flare project that is not bound to Perforce, even if, like me, you normally work with a bound project. When I described how to bind your Flare project to Perforce, I suggested that you kept a copy of the unbound project file as well. If you did that, you will need it now. Otherwise, the simplest way to make one is to take a copy of your bound .flprj file, then open the file with a text editor. Locate the binding string, which will look something like this:

SourceControlBound="true"
SourceControlDatabase="Perforce Project"
SourceControlProviderType="Perforce SCM"
ProjectGuid="1166a5ab-0bf4-4605-9dd4-80c53351a685

and replace it with this:

SourceControlBound="false"

This file is now your unbound project, and you can open it instead of the bound one as required. Check this into Perforce now so you have it available for the next time you need it.

Background to moving and renaming Perforce files in Flare

Moving and renaming Perforce files in Flare is difficult because:

• You have to use Flare to move and rename files, or face the prospect of updating all your broken links manually afterwards.
• In a bound project, Flare doesn’t send Perforce the correct instructions when moving or renaming files, so you have to complete the operation directly in Perforce afterwards. This is why you need an unbound project for this bit, as if you let Flare try to tell Perforce what to do, the result is simply wrong and adds to the mess.
• Perforce doesn’t allow you to move or rename a file unless the old file is still in your workspace and the new file is not yet in your workspace. If you have moved or renamed a file in Flare, this won’t be the case, so before you can do the operation directly in Perforce, you need to take a safe copy of the new file, reinstate the old one, do the move or rename in Perforce, then overwrite the Perforce-renamed file with the safe copy you took earlier. Before Thomas came into my life, I was going to talk you through this painful and error-prone process.

Perforce’s wonder command – Reconcile Offline Work

Fortunately, Perforce includes the Reconcile Offline Work command. This allows you to work on your files outside Perforce, then select a file or folder and ask Perforce to reconcile your changes with the depot. The resultant dialog displays three types of file:

• files in Perforce that you have changed in your workspace but are not checked out of the depot
• files in your workspace that are not in the depot (these may be completely new files, or the moved or renamed versions of existing files)
• files in the depot that are no longer in your workspace (these may have been intentionally deleted, or they may have been moved or renamed).

You can inspect the files shown in the dialog, deselect any files you don’t want to include in the reconciliation, then perform the reconciliation. This adds the selected files to a changelist of your choice. Any changed files are checked out and marked in the changelist for check in. New files are marked to be added, and missing files are marked to be deleted.

There is a small problem with this approach (but, believe me, it’s far smaller than the tedium and likelihood of errors with any alternative method). When you move or rename a file directly in Perforce, the action is saved as a linked deletion/addition pair. That means the file is still effectively the same file, and the move or rename is visible in the Perforce change history. If you do the move or rename in Flare then use Reconcile Offline Work to update Perforce, no direct link is maintained in Perforce between the old and new files. But if you are disciplined about your use of changelists, you can easily ensure that your changelist contains deletion/addition pairs, so maintaining the link in the changelist. The steps below explain how to do this.

Controlling Perforce’s Wonder Command – the Ignore list

There is other small problem with Reconcile Offline Work. It will offer to reconcile everything in your project folder that isn’t already in Perforce. By default, this will include all the Output files, the temporary files, the Analyzer files etc. You can easily stop this by creating a Perforce ignore list for each project. This may have already been done for your Flare project, but if not, it’s easy and I recommend that you do it. If you don’t have an ignore list, you will have to check the list of reconciled files extra carefully, and manually remove anything that doesn’t need to be in Perforce. These instructions assume you’ve set up an ignore list.

Using Reconcile Offline Work to action moves and renames

I strongly recommend that before moving or renaming files in Flare, you start with no checkouts in the project you are working on, and with your Flare project in as clean a state as possible. This will help maintain a clear and accurate audit trail of the operation, which could be useful to those working on the project in the future. So, if at all possible:

• Check in any files in your project that are currently checked out. When you do the move/rename, Flare may change many other files in your project to adjust links, and if the file is already checked out, it won’t show in the list of files to be reconciled, so won’t get included in the same changelist as the other changes related to the move or rename .
• If you have created any new project files that aren’t yet in Perforce, but should be, add them to Perforce now.
• Delete any unnecessary files in your project area that are not in Perforce and are no longer required, unless they are in your Perforce ignore list.

Ready to go?

1. In Flare, action the moves or renames as required, accepting Flare’s request to update links as necessary. Try to restrict your Flare changes to just the move or rename and related changes, as this will make it easier to understand the change history for these files later on. You can always do any additional changes in another changelist immediately afterwards.
2. In Perforce, select the root folder for the project that contains the changes, right-click and select Reconcile Offline Work.
3. Review the files shown in the Reconcile Offline Work dialog box and make sure you are happy with the actions that will be taken.
   • The first section (Modified files) contains files that weren’t moved or renamed themselves, but Flare has needed to update as a result of the move or rename. If you have project files checked out elsewhere, and Flare has had to update links in any of these files as part of the rename sequence, they will not show up here. This won’t stop you completing the move/rename operation, but it will mean that not all files affected by the move/rename are in a single change list.
   • The second section (Local files not in depot) lists the files that need to be added to Perforce. These will include the new files that were created as a result of the move/rename. If you don’t have a Perforce ignore list for this project, you will also see a large number of Flare working files in this list, and if you have other files in your project that have not yet been added to Perforce for any reason, you will see them here too. You can manually deselect the files that aren’t applicable, although I prefer to work in a way that ensures all files here are relevant, as this avoids errors and helps maintain a clean audit trail of changes.
   • The third section (Depot files missing from workspace) lists the files that need to be deleted from Perforce. These will include the old versions of the files that were moved/renamed, and may also include other files that are in Perforce and no longer in your workspace. Again, you can manually deselect the files that aren’t applicable to the move/rename if necessary. In any case, you should end up with the same number of selected files in this section as in the second section as every addition should correspond to a deletion.
4. When you are happy with your selections, select the drop-down by Add files to pending changelist and select New, then click Reconcile. This creates a changelist called Reconciled offline work which contains the Perforce changes for this move/rename operation.
5. Review the changelist, change the description to something meaningful, and submit it. Job done!
6. If you normally work in a bound Flare project, close the unbound project and re-open your bound project.

If this has helped you, please let me know. If you have any questions, I’ll try to answer them. If you have an even better way to handle moves and renames in Flare projects that are stored in Perforce, I’d love to hear about them.

© Marjorie Jones February 2014

Creating a Perforce Ignore List for Flare Projects

A Flare project contains a number of files that don’t need to be checked into source control, for example, temporary files, output files and reports. If you use Perforce as your source control system, sometimes you find yourself with change lists full of files that you don’t want to check in, all of which have to be manually identified and deselected before you can check in the files you really have changed.

Perforce allows you to create an ignore list, which is a text file defining project files that you want Perforce to ignore, and this is an excellent way to deal with the Flare project files that don’t belong in source control. Here’s how to set one up for your Flare project.

First, you need to tell Perforce where to find the information about the files to ignore. We’re going to use a file called .p4ignore.txt to contain the list of files to ignore, and tell Perforce about this file by setting a system environment variable (you have to do it this way because this option is a hang-over from the Perforce command line interface, P4). Then we’ll create a file with this name for each project and check that into Perforce in the project folder. Once you have done this, Perforce will no longer attempt to manage any files in the ignore list.

Setting the environment variable

To set the environment variable (instructions are for Windows 7, other Windows versions are similar):

1. Go to Start > Computer, right-click on it, then select Properties > Advanced System Settings > Environment Variables.
2. In the top section of the dialog box (User variables for <your username>), click New, and add a variable with Variable name P4IGNORE and Variable value .p4ignore.txt. You must set the Variable name exactly as specified here, but you can choose a different filename instead of .p4ignore.txt. You may want to use a different name, for example, if your developers also use Perforce ignore files and have a different naming convention.
3. Click OK, and OK again to exit.
4. If P4V was open when you did this, close it and reopen it.

If you use Flare and Perforce on more than one computer, you will need to do this on each computer, and each user will need to do it for themselves. The setting is restored after you reboot, so it only needs to be done once in each case.

Creating the Perforce ignore file

To create the Perforce ignore file:

1. Open your favourite text editor and enter the following:

# Perforce Ignore file for Flare projects
Analyzer\*.*
Output\*.*
Project\Reports\*.*
Project\Users\*.*
SourceControl\*.*

2. Save the file as .p4ignore.txt in your Flare project root folder. If you chose a different filename when you created the P4IGNORE environment variable above, use that name instead.
3. Check this file into Perforce as part of the project.

From now on,  Reconcile Offline Work and other similar operations in Perforce will ignore the files specified in the ignore list, and will not offer them for check in. And if you, or anyone else tries to add a file in the ignore list to Perforce, a warning is displayed.

If you use a project template for creating new projects, you will probably want to add this file to the project template too.

Customising the ignore list

The ignore file above will be sufficient if you use the default Flare project settings, but you can add any file or folder specifications to the Perforce ignore file to reflect the way you work. For example, if you use Flare’s Global Project Linking, you may want to exclude the globally linked files from Perforce for all projects except the global project itself.

If you want to customise the file content further, you may find the following helpful:

• Use # at the beginning of a line to denote a comment. You can use this as required.
• If you want to exclude the file Never_add_to_perforce.dat, add this line to the Perforce ignore file to exclude all files of this name wherever they are found in the project structure.

Never_add_to_perforce.dat

• If you want to exclude all files with the .tmp file extension, add this line to the Perforce ignore file to exclude all files that end in .tmp wherever they are found in the project structure

*.tmp

• If you want to exclude all files with the .tmp file extension except a specific file Add_to_Perforce.tmp, which you want to be able to add as normal, add the following lines to the Perforce ignore file (the ! specifies an exception to the ignore rule)

*.tmp
!Add_to_Perforce.tmp

If this has helped you, please let me know. If you have any questions, I’ll try to answer them. If you have other tips for working with Flare projects in Perforce, I’d love to hear about them.

© Marjorie Jones February 2014