About Source Control and Multi-Authoring

Source control is a process that allows you to store your project files in a central location and determine which individuals have access to those files. By using a system where individuals must "check in" and "check out" files to edit them, you can ensure that there are no file conflicts when many individuals are working on the same project (multi-authoring teams). You can also revert back to earlier versions of source control files if necessary. Source control is even useful for single authors because it provides a means for maintaining a constant backup of all project files.

No. Flare does not use a proprietary source control system within the Flare application. Instead, Flare allows you to connect (or "bind") your project to an existing third-party source control application that is separate from Flare.

Built-in support is available for Microsoft Visual SourceSafe and Microsoft Team Foundation Server. In addition, an API allows you to configure your project for integration with other source control tools (see Using an API to Integrate Source Control). You also have the option of manually adding your Flare project files to any source control tool, rather than using Flare's built-in integration.

This depends on how you work in your company. Someone (perhaps a network administrator) needs to set up your source control program (such as Microsoft Visual SourceSafe) and create the necessary database(s) in it. This individual may also set up the "rights" to all persons who have access to the necessary databases and files. If you are working on a multi-author team, each writer on the team needs to have a local copy of the Flare project and will be responsible for checking in and checking out files as necessary.

If you are manually adding files to a source control application (rather than using the built-in Flare integration), you can transfer any and all files in a Flare project. This includes your main FLPRJ file, all content files, all project files, and all output files.

If you are using Flare's built-in source control integration, you can transfer the main FLPRJ file, all content files, and all project files. You cannot transfer the output files. In an ideal workflow, you would only need to transfer the files mentioned, and when you are ready to generate output, you would publish the output files to another location where users can access them (such as a website or network drive).

Following are definitions for some of the common phrases used in Flare's built-in source control system:

• Bind This means to connect your project to an external source control application (such as Microsoft Visual SourceSafe). After doing this, you can then take advantage of all the automated source control tasks (such as check in, check out, instant messaging, and so on).
• Check In This means to copy your local Flare files to the source control application, overwriting the copies stored in the source control tool. This enables other authors on your team to access and edit the latest files (unless, of course, you keep the files checked out at the same time).
• Check Out This means to copy the latest source control files to your local Flare project and remove the "Read Only" designation from them so that you can edit the files.
• Get Latest Version This means to copy the latest source control files to your local Flare project without necessarily checking out the files. This means that the "Read Only" designation will remain associated with the files until you check them out.

Following are descriptions for the primary icons that you may see next to files when using source control:

	This indicates that you have the file checked out from source control. You can check in the file when you are ready. See Checking In Source Control Files and Checking Out Source Control Files.
	This indicates that you have a file in your project but have not yet added it to the integrated source control application. This might occur, for example, if you create a new topic and do not add the file to source control during the topic creation process. To resolve this, simply right-click on the file and select Source Control>Add. See Adding Files to Source Control.
	This indicates that the file is added to source control but is not currently checked out, which means that it contains a "Read Only" designation in its properties. In order to edit the file, you must check it out from source control. See Checking Out Source Control Files.
	This indicates that the file is currently checked out to another user. You can send a request to the user, asking that person to check in the file so that you can check it out. See Requesting a User to Check In Source Control Files.
	This indicates that the file is not current (i.e., the local copy of the file is older than the source control copy). This might happen, for example, if another user checks out the file, makes changes to it, and checks it back in to source control. If this occurs, you can check the file out or get the latest version of the file from source control. See Checking Out Source Control Files or Getting the Latest Version of Source Control Files.
	This indicates that the file is deleted from source control, but you still have a copy of the file on your local machine. If necessary, you can add the file to source control. See Adding Files to Source Control.

Following are the basic steps for using Flare's source control integration for a multi-author team:

1. Set Up Source Control Application Install the source control application and set up the database and any folders where you want to place the project. Also, assign permissions to the proper individuals. This task may be performed by someone else, such as a network administrator.
2. In Flare, do one of the following, depending on whether you are creating a new Flare project or using an existing one:

   • Create and Bind New Project Create a new Flare project and simultaneously bind it to an integrated source control application. See Creating a New Project.

     OR

   • Bind Existing Project If you have an existing Flare project on your local machine, bind the project to the source control application. See Binding an Existing Project to Source Control..

   Note: Only one of the authors needs to perform this task. The other authors on the team can follow Step 3 below.

3. Import Project Other users on the team can easily import the project from source control. This creates a copy of the Flare project on the author's computer. See Importing a Project from Source Control.
4. Check Out Files When you need to work on any of the Flare project files, you can check them out. Checking out files means to copy the latest source control files to your local Flare project and remove the "Read Only" designation from them so that you can edit the files. A red check mark is displayed next to each file that is checked out. See Checking Out Source Control Files.
5. Add Files When working in a project that is connected to a source control application, there may be occasions when you have files in your local copy of the project that are not yet part of the source control copy. For example, when you add a new topic in your local copy of the project, that file will not be included in the source control copy of the project until you add it. See Adding Files to Source Control.
6. Check In Files When you are finished editing files, you can check them in to source control. Checking in a file overwrites the old copy of the file in the source control database with the new one from your local machine. So even if others will not be working on that file, it is a good idea to periodically check in files so that you have a backup in source control. See Checking In Source Control Files.
7. Request to Check In Files If you attempt to check out a source control file and discover that another user already has that file checked out, you can automatically send a request to that user to check in the file. This is a completely automated process involving instant messaging or email. Not only are the messages sent to the appropriate individuals automatically, but the mechanisms for checking in and checking out the necessary files are built in to those messages. This means that you and the other authors on your team do not need to hunt down the correct files manually. See Requesting a User to Check In Source Control Files.
8. Request to View Files If you want another author to review a file and provide comments, this can be done by performing a request to view files. Similar to the process for requesting check-ins, this feature uses instant messaging to streamline the workflow. See Requesting a User to View Files.

Following are the basic steps for using Flare's source control integration for a single author:

1. Set Up Source Control Application Install the source control application and set up the database and any folders where you want to place the project. Also, assign permissions to the proper individuals. This task may be performed by someone else, such as a network administrator.
2. In Flare, do one of the following, depending on whether you are creating a new Flare project or using an existing one:

   • Create and Bind New Project Create a new Flare project and simultaneously bind it to an integrated source control application. See Creating a New Project.

     OR

   • Bind Existing Project If you have an existing Flare project on your local machine, bind the project to the source control application. See Binding an Existing Project to Source Control.

3. Check Out Files When you need to work on any of the Flare project files, you can check them out. Checking out files means to copy the latest source control files to your local Flare project and remove the "Read Only" designation from them so that you can edit the files. A red check mark is displayed next to each file that is checked out. See Checking Out Source Control Files.
4. Add Files When working in a project that is connected to a source control application, there may be occasions when you have files in your local copy of the project that are not yet part of the source control copy. For example, when you add a new topic in your local copy of the project, that file will not be included in the source control copy of the project until you add it. See Adding Files to Source Control.
5. Check In Files When you are finished editing files, you can check them in to source control. Checking in a file overwrites the old copy of the file in the source control database with the new one from your local machine. So even if others will not be working on that file, it is a good idea to periodically check in files so that you have a backup in source control. See Checking In Source Control Files.

Following are some additional tasks and features related to source control:

• History You can view the history of a particular source control file. See Viewing the History of Source Control Files.
  • Version Displays a number for each version of the file. The lower the number, the older the version. The higher the number, the more recent the version.
  • Users Displays the name of the user who has been working on the file.
  • Date Displays the date and time when the action has occurred.
  • Action Displays the action that has taken place for the file (e.g., check in).
  • Comment Displays the comment (if any) associated with the file. A comment can be added to a file when you check that file in to source control. This enables you to maintain an audit trail for the file's history.
  • Get selected version You can perform a "get" of a particular version of a file, thus rolling back to that version of the file. See Rolling Back to an Earlier Version of a File and Getting the Latest Version of Source Control Files.
  • Show differences You can view the differences between two versions of a file. If you select one row in the History dialog and view the differences, you will see the content differences between the version that you selected and the version of the file in your local copy of the Flare project. If you select two files in the History dialog (by holding down the CTRL key) and view the differences, you will see the content differences between those two versions of the file.
• Differences You can view differences between files in the following ways. For more information, see Viewing Differences in Source Control Files.

  • Two versions of same source control file (history/roll back) You can view code and content differences between two source control versions of the same file. This is useful if you need to roll back to an earlier version of a file. See Rolling Back to an Earlier Version of a File and Getting the Latest Version of Source Control Files.

    example

    Let's say that you have been working on a particular topic for a few days. Each day you check out the latest version of that topic file from source control, make your changes, and check the file back in to source control at the end of the day. At a certain point, you determine that you need to "roll back" to an earlier version of the file, using it to replace the latest version. Therefore, you use this feature to view the highlighted differences between the current version and an older version of the file. Once you have identified the older version that you want to use, you can perform a "get" of that version.

  • Two different source control files You can view code and content differences between the source control version of two different files.

    example

    Let's say that you have two topics that are quite similar in some aspects, but different in others. Rather than trying to scan the two topics with your eyes to determine the differences, you can select the two files in the Flare interface and use this feature. Flare will retrieve the source control versions of the two topic files and display the content and code of each side-by-side, highlighting the areas where differences occur.

  • Local versus source control version of a file You can view code and content differences between the local version of a file and the source control version of that file.

    example

    Let's say that you check out a procedure topic from source control and then add some lines of text to your local copy of that topic file. You save your changes. Later that day, you want to revisit the new content that you wrote, but you cannot remember exactly which lines of text you added. Therefore, you use this feature to highlight the text differences between your local checked-out version of the file and the version stored in the source control application. The new lines of text are highlighted on the side displaying the local version of the file.

  • Local versus source control version of all files in a folder You can view file differences between the local version of the files in a folder and the source control version. Most likely, you will use this to view all of the difference between the local files and source control files in either your Content Explorer or Project Organizer.

    example

    Let's say that you have checked out all of the files for a Flare project. During the course of the day, you add several new topics to the project, but you forget to add them to source control during the creation process. At the end of the day, you check in all of the files in the project to source control. Afterwards, you realize that you forgot to add the new files to source control. Therefore, you use this feature to see the file-level differences between your local copy of the Content Explorer root folder and the source control copy. The differences are color coded, so you can easily identify the files in question. (By default, the files that are included only in your local copy are green, and the files that are included only in source control are red.) You can then right-click on the files that were added only to the local copy, and you can select to add them to source control.

• Unbind You can unbind ("disconnect") a project from source control. See Unbinding a Project from Source Control.
• View Checked-Out Files You can use the Pending Check-Ins window pane to view all of the files that you have checked out and need to be checked in. You can use the File List window pane to view files that are checked out by other authors. See Viewing Files That are Checked Out and File List Window Pane.

• API If you are working with a source control application other than those directly supported in Flare (i.e., Microsoft Visual SourceSafe and Team Foundation Server), you can use the Microsoft Source Code Control API (SCC API) to integrate that application with your Flare project. See Using an API to Integrate Source Control.

  Note: It is not mandatory that you use the SCC API to use a source control application for your Flare project files. It is only necessary if you want to take advantage of the source control integration features inside Flare. Otherwise, you can manually add your Flare project files to any source control application.