Dual-Bound Projects

Dual-bound means that your project has a first binding to a third-party source control provider—such as Git, TFS, SVN, or Perforce—and then a second binding to Central. With this model, you use the first source control binding to do most of the version control work; the Source Control ribbon in Flare is used only for tasks related to the first binding. Then periodically, you will use the MadCap Central window pane in Flare to upload (or “push”) the latest files from your local copy of the project up to Central via the second binding; the Source Control ribbon in Flare is not used for the second binding.

Note It is possible for multiple people working on a dual-bound project to push files to Central. However, if you are using a source control provider other than Git for the first binding, the most recently pushed files are the ones that are used in Central. In other words, the last person to push "wins." To avoid issues, be sure that you have the most recent version of file changes from all other writers in your local project before you push. You may even want to limit users' permissions (see Setting User Permissions) so only one or two people are allowed to push files.

Note Your first source control binding (between Flare and a third-party provider) should be done from the Flare interface, rather than from another tool. Otherwise, Flare and Central will not recognize that binding. If you already have a project that was bound using another tool, you have a couple of options:

  • You can remove the binding and then bind again using Flare.
  • You can create a new Flare project, importing from source control. This method allows you to retain the repository.

How to Use a Dual Binding—Perforce, Subversion, TFS, and Other Providers

  1. Open the project in MadCap Flare, and make sure your project is already bound to a third-party source control provider. See the Flare online Help.
  2. Select View > MadCap Central. The MadCap Central window pane opens.
  3. If you are not yet logged in, enter the same user name (i.e., email) and password that you use for logging into Central, and click Log In.
  4. Upload (bind) your project to Central. See Uploading (Binding) Projects.

    Because you are dual-bound, Flare will prompt you to check out your Flare project file before you can upload the project. This allows Central to add an ID to the project file when you upload the project. This ID links the project to Central.

  5. Check in the Flare project file to your third-party source control provider. This adds the Central ID in the project file to your source control repository, making it available to other users. See the Flare online Help.
  6. In Central, assign users to the new project and make sure they have “Push” permissions. This gives the users the ability to push local content to the project on Central. See Associating Users With Teams and Projects and Setting User Permissions.
  7. Newly assigned users must now do one of the following, depending on whether or not they already have a copy of the Flare project on their local machine:

    • Have a Local Copy Get the latest version of the Flare project file from the third-party source control provider. See the Flare online Help.
    • Do Not Have a Local Copy Import the project from the third-party source control provider using the Import Project from Source Control Wizard. See the Flare online Help.

      Note If your project is already bound to a third-party source control provider other than Git—i.e., you are working in a dual-bound model as opposed to a single-bound model—the Import option in the MadCap Central window pane will be disabled. You will have to import your project directly from source control using your non-Central binding.

      If you already have the project on your machine, you do not need to reimport the project from source control. Instead, you can get the latest version from source control by using the Flare Source Control ribbon (see the Flare online Help).

      Be sure that you have the latest version of the project because when the project is initially uploaded to Central, a Central ID is added to the project file. You must have the Central ID in your local copy of the project file in order for Central to recognize that your copy of the project is linked to the copy in Central.

    Either option will give users the most current version of the project file, with the Central ID. This links each user's local copy of the project to Central.

  8. In Flare, make changes to your files. You should manage all of your file changes using your third-party source control provider, using the following actions:

    • Check In Check in your changes to source control. See the Flare online Help.
    • Get Latest Get the latest version of your teammates' changes from source control and add them to your local project. See the Flare online Help.
  9. When you are done making changes, push your final changes to Central. To do this, click in the MadCap Central window pane. See Pushing in a Dual-Bound Model.

Example You are working on a team of writers and your project is bound to Microsoft Team Foundation Server (TFS). Therefore, that is your primary source control provider, and the source control connection between Flare and Central serves as a secondary source control provider.

When you first start working with Central, you have to upload (or bind) the project to Central. To do this, click in the MadCap Central window pane.

Because the project is bound to TFS, you will have to check out the project file before you can bind the project (Flare will prompt you to do this). Binding the project will establish the connection between Flare and Central, and creates a copy of the project in Central.

After you bind the project to Central, an ID is added to the Flare project file. You need to check in the updated project file so other users on your team can access it. To do this, click Check In All in the Flare Source Control ribbon.

If any writers on the team do not already have a local copy of the project, they should import the project from TFS so they can work on the project locally (they cannot import from Central because the project's primary source control location is TFS). To import the project, they will use the Import Project From Source Control Wizard. Importing the project from TFS will ensure that they have the Central ID in their project, which links their copy of the project to Central. This is the dual binding. For more information about importing projects from source control, see the Flare online Help.

Writers on your team who already have the project locally do not need to reimport. They simply need to get the latest version of the project by clicking Get Latest All in the Flare Source Control ribbon. This ensures that they have the Central ID in their project, linking it to Central.

Now that everyone has the updated project file, you can all work on the project and make changes using TFS. However, a user with the "Manage Teams/Projects" permission also needs to assign your teammates to the project in Central (see Associating Users With Teams and Projects).

As you work on files in Flare, you should check out your files using Flare's Check Out feature on the Flare Source Control ribbon (or using automatic checkouts, if you have this enabled).

After you are finished making changes, you should check in your changes to TFS. You can do this by clicking Check In All on the Flare Source Control ribbon. This will upload your changes to TFS.

Once your changes are checked in, you should make sure that you have the latest version of your teammates' files, as well. To do this, click Get Latest Version All on the Flare Source Control ribbon. This will download the latest changes of all of the files to your local version of the project.

When you and your teammates are finished making changes, you need to synchronize your local copy of the project with the copy of the project in Central. To do this, click in the MadCap Central window pane.

This will push your local changes up to Central. It is important to remember that the last person who pushes their changes to Central wins, so be sure that everyone has the latest version of the project files before you push (or even limit some users' permissions so they are not able to push; see Setting User Permissions) so you do not have out-of-date files in Central.

Once your files are up in Central, you can publish output and manage your project.

How to Use Dual-Binding—Git

  1. Open the project in MadCap Flare.
  2. Be sure your project is already bound to Git. See the Flare online Help.
  3. Make sure all changes are committed before binding to Central. See the Flare online Help.
  4. Select View > MadCap Central. The MadCap Central window pane opens.
  5. If you are not yet logged in, enter the same user name (i.e., email) and password that you use for logging into Central, and click Log In.
  6. Upload (bind) your project to Central. See Uploading (Binding) Projects.

    When you bind the project, an ID is added to the project file. This ID links the project to Central.

  7. Push the Flare project file to Git. This adds the Central ID in the project file to your Git repository, making it available to other users. See the Flare online Help.
  8. In Central, assign users to the new project and make sure they have “Push” permissions. This gives the users the ability to push local content to the project on Central. See Associating Users With Teams and Projects and Setting User Permissions.
  9. Newly assigned users must now do one of the following, depending on whether or not they already have a copy of the Flare project on their local machine:

    • Have a Local Copy Pull the latest version of the Flare project file from Git. See the Flare online Help.
    • Do Not Have a Local Copy Import the project from Git using the Import Project from Source Control Wizard. See the Flare online Help.

      Important If you are using a Git/Central dual-binding, you can import projects from Git (using the Import Project From Source Control Wizard) or from Central. The project will be the same. However, if you import from Central, you will only be able to push changes to and pull changes from Central. If you import from Git, you will be able to push changes to and pull changes from Central as well as your main Git repository. This is because the project in Central has no connection to the original Git repository, and if you import from Central you will not have those source control bindings.

    Either option will give users the most current version of the project file, with the Central ID. This links each user's local copy of the project to Central.

  10. In Flare, make changes to your files. When working in a Git/Central dual-bound situation, you can make changes to both Central and Git, using the following actions:

    • Pull Pull your teammates' changes from Git and add them to your local project. See the Flare online Help.

    • Push Push your changes to source control. See the Flare online Help.

    Note It does not matter which location (i.e., Git or Central) you push to or pull from first, as long as you push the files to both Git and Central and that everyone on your team uses the same workflow.

  11. (Optional) If the changes in Git or Central become out-of-sync with each other (i.e., changes are made in one location but not the other), the Resolve Conflicts dialog opens. If this happens, use the dialog to accept or reject other users' changes. See the Flare online Help.

  12. When you are done making changes, push your final changes to Central. To do this, click in the MadCap Central window pane. See Pushing in a Dual-Bound Model.

What’s Noteworthy?

Important There are several different workflows you can use when working with a Git/Central dual-binding. The steps above are only one example of how you might perform this process. Because of the potential for file conflicts, it is essential that you establish a workflow for using a Git/Central dual-binding, and make sure that all your team members follow the same steps.

Important If your project is dual-bound to MadCap Central and a third-party source control provider, unbinding the project from source control will also remove the binding to Central.

Note If you are using Git as your third-party source control tool for the first binding, the dual-bound model works slightly differently than it does if you are using another source control provider. In this situation, you will still use the MadCap Central window pane and Source Control ribbon in Flare to manage your changes. However, you are able to pull and push files from and to either Central or your Git repository. As a result, your Git repository and your Central repository might be completely different, and you may encounter conflicts. In this situation, Flare's Conflict Resolution dialog will open and you can accept or reject the changes. It is recommended that you establish an internal workflow to dictate the order in which you pull and push from and to each repository to prevent conflicts and ensure that your files in Central stay up-to-date.

Note Just because you have a previous third-party binding to a project, this does not mean you must keep working that way. In other words, you always have the option of unbinding your Flare project from that third-party source control provider and then working in a single-bound model instead. But if you desire to continue working with the other third-party tool, you can do so by using the dual-bound model.

Note If your project is dual-bound to Git and Central, you can create new branches in Flare (see the Flare online Help). However, you can only push files from the master branch to Central. Single-bound projects do not support branches.

Note If you are using a Git/Central dual-binding, and you encounter conflicts in one repository (i.e., Git or Central), you will likely encounter them in the other location as well. Conflicts in one repository will most likely need to be resolved in the other repository. See the Flare online Help.

Note For more information about source control tasks and managing dual-bound projects with the various third-party providers, see the Flare online Help.