Branching in Checklists

When working with checklists, you can use branching. See Branching.

This is extremely important due to the nature of content associated with checklists. When you are working on a checklist related to projects (as opposed to a generic checklist), it usually coincides with content that is in a state of development, rather than content that has already been published. And branching is the best way to isolate content that is in a state of development so that checklists can be associated directly with it.

Note Branching in checklists is intended only for "Project File" checklists (i.e., those where you select files from a project), not for "Generic Lists."

Permission Required?

No special permission is required for this activity. All authors who are associated with the project are allowed.

How to Create a Checklist for a Specific Branch

  1. Select Projects on the left side of the interface, then click a project name to open it.
  2. At the top of the interface, click Checklists.
  3. In the toolbar click Add.
  4. On the Settings tab, give the checklist a Name and make sure the Checklist Type is Project Files.
  5. From the Branch field, select the name of the branch to be associated with the checklist.
  6. Complete the rest of the options on this tab and the others as you normally would. See Creating Checklists.

Example Your company's product is on version 5.0, and the initial plan is to add Feature A, Feature B, and Feature C in the new, upcoming release of version 6.0. Therefore, in Flare you create a branch called "Feature-A," another called "Feature-B," and a third called "Feature-C." You synchronize your changes with Central.

In the project on Central, you open the Files page and switch to the Feature-A branch. Then, you add content for Feature A.

Later, you decide to work on Feature B for awhile, so you switch to the Feature-B branch and add content. The next day, you focus on Feature C, so you switch to Feature-C and do some work.

There are many new topics and other files that you eventually end up adding for each of these branches, and there are several existing files that you update for each one as well. In addition, there are many tasks (e.g., edit, add to table of contents, spell check, review) that you want to keep track of for each file that you work on, just to make sure you are completing everything that is necessary.

You need some checklists.

In Central, you create a new topic checklist called "Feature A Checklist," and you select the Feature-A branch when adding that checklist.

For that checklist, you select many topics that are associated with the documentation of that new feature.

You do the same for the other two new features, and you associate several different topics with each of those additional two checklists. So in the end, you have three checklists: Feature A Checklist, Feature B Checklist, and Feature C Checklist. Each of those checklists is associated with its related branch.

As you continue to work on the documentation for each feature in the appropriate branches, you update each of the three checklists as necessary to track your progress.

Why did you create those separate branches? Why not just do everything in your "master" branch?

Well, at some point during the release cycle, a decision is made that Feature B is not ready and will take longer than anticipated. It won't go live until version 7.0. If you had done all of the work for each of the three features in the master branch, you'd have a big mess on your hands, because you'd have to figure out a way to back out the changes only for Feature B. But because you separated the work into three feature branches, it's no problem.

Eventually, you complete your work for Feature A and Feature C, and you wrap up the checklists for each. You have confidence that all the necessary documentation tasks have been completed for each feature.

And eventually in Flare you merge your Feature-A and Feature-C branches into the master branch. Then from that branch, you publish the final documentation output for version 6.0 of the product.

What’s Noteworthy?

Warning — Losing Statuses When Switching Branches

The Branch field is also available when you need to edit a checklist, so it is possible to switch to a different branch than the one you originally started with. However, use caution when doing this, because statuses are not stored separately on the same files across branches. The status will only be retained if the file is unique to that branch.

For example, let's say you have a branch called "Feature-A" and another called "Feature-B." The topic called "Getting Started" exists in each of those branches. You've created a checklist pointing to the Feature-A branch, and you've set the status for the Getting Started topic to "Complete."

Later, you open the properties for that checklist and switch it to use the Feature-B branch. You change the status for the Getting Started topic to "In Progress."

Then, sometime later you open that checklist, bring up the properties, and switch the branch back to Feature-A. When you look at the status for the Getting Started topic, it now says "In Progress." It did not retain the "Complete" status that you originally set for that branch.

However, your Feature-A branch also has a topic called "Feature A Requirements," and this topic is unique to that branch. No other branch contains that topic. You've set the status for that topic in your checklist to "N/A." You switch the checklist to use another branch and do some work in it. When you switch the checklist back to the Feature-A branch later, you'll notice that this unique topic still has its original status.

For these reasons, we recommend that you avoid trying to use different branches for the same checklist. Instead, create a separate checklist for each branch where you want to track progress.

Note For more detailed information on Git branching and how to use it with Flare projects (including creating, merging, and publishing branches to Central), see the Flare online Help and the related source control branching videos.