The 2021 r3 service release of MadCap Flare introduced many source control enhancements, including improvements to the interface and new support for working with branches on MadCap Central. So, I thought this might be a good time to talk about source control in this column; in particular the benefit of branching, and how you can now use branching on MadCap Central.
Why use source control?
Source control mainly benefits Flare users who work within teams. It enables each team member to have their own local copy of the Flare project, while ensuring that all changes are synchronised across the team via a remote source control repository.
However, source control can also be extremely useful even if you are a sole author with no other collaborators on a Flare project. For example, source control provides you with a full history of all versions of the files in your project and enables you to go back to any previous state of the project. This can sometimes be a life saver!
Source Control also provides the opportunity for branching, which enables you to work on different concurrent variations of your project without needing to use conditions. This could be useful, for example, if you wanted to be able to create and edit a new set of topics covering features that have not yet been released, while still maintaining the topics for the current release version of the product. In this case, you might create a new branch called 'new-features' in addition to the main 'master' branch in which you maintain the current version. When the new features have been released into the product, you could then potentially merge your 'new-features' branch back into the 'master' branch.
Using MadCap Central for source control
As well as offering other features such as Analytics, MadCap Central provides a distributed Git-based source control system. An advantage of distributed source control is that you have your own local copy of the source control repository and can continue to do source control operations such as committing changes even when offline. Up until the recent service release of Flare, a significant limitation of using MadCap Central as your source control repository was that it did not support branching. However, with Flare 2021 r3 and the current version of MadCap Central, branching is now possible.
Creating a new branch in Flare
Let's imagine that you are working in a Flare project that has been bound to Central for source control, and you now wish to create a new branch to document a new feature.
The easiest way to create a new branch is to do the following:
- Open the Branch Management dialog (on the Source Control ribbon, click the main part of the Branch icon, not the drop-down arrow beneath it).
- Click Create to open the Create Branch dialog.
- Enter a new Branch Name, and select the Switch to branch check box, before clicking Create.
As a result, the new branch is created and has become the active branch. You can confirm this by looking at the useful new indicator on the right-hand end of the Status Bar at the bottom of Flare's interface.
This shows the currently active branch. You can now close the Branch Management dialog.
Uploading changes to MadCap Central
When you upload (push) your changes to MadCap Central, it is important which branch is currently active. This is because Flare only uploads commits from the active branch. So, if you want other team members to be able to contribute to your 'new-features' branch, you will have to push changes when this branch is active otherwise, the branch remains private to you.
Switching to a branch created by a team member
Let's say that one of your team members updates their local copy of the project from Central. Although the content for all branches is pulled down to their local Git repository, they will not see the new branch that you have created, either in the list of branches in the Source Control Explorer, or in the drop-down list of branches available from the Status Bar. So how can they switch to your new branch?
The solution I discovered by reading Flare's comprehensive documentation is to open the Branch Management dialog, and select the Remotes tab (which is new in Flare 2021 r3).
To switch to the branch, select it on the Remotes tab, and click Switch. The Branch then becomes active and is added to the Locals tab as well as to the list of available branches in all other parts of the Flare interface.
Viewing and publishing branches on MadCap Central
In the MadCap Central portal, you can choose between the different branches when you view the Files or Commits for a project.
You can also choose to build a specific branch in Central, for example if you wanted one of your internal SMEs to review the draft documentation that you have written in a new branch for unreleased features.
The new support for branching in MadCap Central is a significant and welcome enhancement. It provides more flexibility for working with variations of your content without the complexity of conditions, and matches the branching capabilities of other Git-based source control providers.
Training and Consulting in MadCap Flare