Branching

Git branches are supported on Central for topic reviews, building output, sites, files, and commits. From Central, you cannot create or merge branches (you must do this in Flare), but you use branches in various ways. For example, in Central you can commit changes to a specific branch when editing a file in Central.

Note Branching is not yet available on Central for checklists or reports. With those features, you are always working with files information from the master branch.

Note Branching on Central is supported for Flare projects that are single-bound to Central, as well as dual-bound projects using a Git-Central setup. Branching is not supported on Central for dual-bound projects that are using Perforce Helix Core, Subversion, or Team Foundation Server as the first binding.

Reviews

From Flare, you can send files in a particular branch for a review on Central. Reviewers (e.g., SMEs and authors) can see which branch a file is coming from on the right side of the interface. However, nothing special needs to be done in order to make edits or comments in the file. See Reviews and Editing Review Files.

Note Reviewers who are authors can alternatively click the file icon in the review package overview or at the top of the Review Editor. The Review Files profile opens to show package information including branch association, and also to update various file settings.

When you bring a reviewed file back into Flare and accept it so that it replaces the original file, make sure you first switch to the correct branch in Flare. The branch associated with each file is shown in a column in the File Reviews window pane in Flare.

Building Output

Central supports building output for specific branches, rather than just the master branch. There are tabs in the toolbar to let you switch from manual builds to automatic scheduled builds. A button in the upper-right corner lets you initiate a build or schedule. Once you click this button, you can point to a specific branch. In addition, a Branch column in the grid displays the branch for which a particular build was generated. See Generating and Scheduling Builds.

Note If you build a target in the Flare project for a particular branch and then publish the output from Flare directly to Central, you will also see the associated branch listed in the Branch column on the Builds page. See Publishing Directly to Central.

Files and Commits Pages

After you push changes from a branch on Flare up to Central, you can switch to that branch on the Files or Commits page. This lets you verify that the files or changes for that branch were indeed sent to Central. A filter field at the top of the drop-down lets you limit the branches shown. See Viewing Project Files and Viewing Project Commits.

Sites

When you create or edit a site, you can select a branch for the output. For example, this is useful if you are generating private output to circulate among individuals in your company so they can see content that is currently under development, but not accessible to the general public. See Creating Sites and Editing Sites.

Workaround for Branching and Checklists

At this time Central does not support source control branching for checklists. When you create and edit checklists in Central, you are always working with the master branch. However, it is possible to develop a workaround for this issue so that you can create checklists for other branches.

The following describes how the MadCap Documentation team uses this workaround, which involves Global Project Linking in Flare.

  1. Our primary Flare project holds content for all of our MadCap Software products. In addition to that main project, we have created several smaller projects, each one designed to hold content in a state of development related to a specific MadCap product (e.g., “Central - Develop,” “Flare-Develop,” “Lingo-Develop”).
  2. In our main Flare project, we check out a branch we have named "develop," which contains a compilation of new documentation as it’s being developed, not the finished result.
  3. We open one of our child "Develop" Flare projects. Based on conditions that are set on files in the main project, we import all of the files for a particular product via Global Project Linking. We do not edit any of these child projects; their sole purpose is to hold a copy of content already existing in the main project.
  4. Each of our child projects has a single binding to Central. So we push the files up to Central. Although we are pushing the master branch for that child project, the content actually originates from our develop branch of the main project. This allow us to create and manage checklists based on documentation that is still in a state of development.

What’s Noteworthy?

Note For more detailed information on Git branching and how to use it with Flare projects (including publishing branches and pushing changes to Central), see the Flare online Help.

Note If your project is dual-bound to Git-Central and you want to change your configuration to a single-bound setup, you can do so by completing the following steps in Flare.

Your Git commit history will be retained when you move from a dual-bound configuration to a single-bound setup. That's because the history is recorded in your local Git repository where your Flare project exists. Removing the first binding will have no effect on the commit history.

  1. Each author on the team should commit all outstanding changes and synchronize each local branch with the corresponding remote branch.

  2. It's possible, or even likely, that not all writers on the team have all of the remote branches locally, and they don't necessarily need to. But between all of the team members, all of the remote branches that you want to keep should be pulled down to someone's local repository by selecting the remote branches and switching to them via Flare's Branch Management dialog. In fact, just one person on the team could do that. Then, once the first binding is removed using the steps below, the local branches can be published (i.e., pushed) to the remote Central repository.

  3. Each author on the team should then complete the following steps:

    1. Select Project > Project Properties.

      You can also remove the first binding by using the Settings view of the Source Control Explorer.

    2. Select the Source Control tab.

    3. Next to the Remotes field, click The browse ellipsis button opens to more options..

    4. Select the origin row (which represents your first binding) and click Remove. This leaves just the Central binding.

    5. Click OK.

    6. In the Project Properties dialog, click OK.