Key Information

Once you have got your project linked to your VCS everything works exactly the same as it does for multi-user editing on projects that are not in a VCS. See Multi-User Editing for full details.

When you use VCS support in Help & Manual there are two copies of your project: A "local" copy, which is the project you are actually working on, and the version control copy in the VCS database. The two copies are actively linked – the VCS "knows" when Help & Manual is working with the files, and Help & Manual also "knows" when someone else is working on the files from the same database.

The functionality is essentially the same as with multi-user editing – the only real difference is that the VCS is automatically maintaining backup copies of your project files in the background. In addition to this the VCS also makes sure that only one person works on any topic at the same time, thus ensuring that you can never create two conflicting versions of the same topic.

See the other topics in this chapter for information on how to link projects to your version control system.

When you open an HMXP project that is linked to a copy in a VCS database, Help & Manual activates the connection to the VCS database and checks whether any changes have been made to the copy of the project in the database since the last time you worked on it. If changes have been made they are updated in your local copy. This also includes changes made by other users who have linked the same VCS database version to local copies of their own. You will see both your own changes and changes made in the meantime by other users.

This updating process is done in the background. Nothing is actually checked out of the VCS database until you start editing topics. This makes it possible to lock only those topics that are actually being edited. When you edit a topic, the topic file is checked out of the VCS database until you save your project.

When you save your work, all the changes you have made are written to your local copy and to the copy in the VCS database. If you have activated automatic check-in and check-out, your updated topic is then checked back into the VCS database so that other users can access it. Otherwise, the topic is not checked back in until you do this manually. If another user then accesses their linked copy it will automatically be updated with the changes that you have made.

When you select a topic or topic file by clicking on it in the Project Explorer, the system first checks to see whether anyone else has that topic checked out of the VCS database.

•If the topic is checked out by another user, you will get a message telling you that it is locked and read-only. You will not be able to edit the topic until the other user saves their work and switches to a different topic. Until the other users saves and checks their copy into the database you will also only see your own older local copy.

•If the topic is "free" you will be able to edit it. The VCS database copy of the topic is checked out while you are working and it appears as read-only to any other users who try to access it.

•When you save your project and move to another topic your changes are saved to your local copy and to the VCS database copy. The topic file is checked back in to the VCS database, after which other users are able to check it out and edit it.

All users working on the project are able to make changes to the Table of Contents (moving topics, creating new topics, deleting topics, editing topic captions in the TOC). If two users make conflicting changes the last one who saves their project will get a conflict resolution dialog asking them to decide if they want to keep their own changes or the changes made by the previous user.

How this works depends on whether you are using automatic or manual check-out. See Auto & manual check-out for more details on this.

Automatic mode: Always select Refresh Project before editing the  Table of Contents

If you are using automatic check-out mode you should always save your project and select Refresh Project in the Project tab to make sure that your local copy is updated with any recent changes made by other users before making changes to the Table of Contents. Then you can confidently make your own changes, after which you should always save immediately to commit your changes to the VCS database.

Manual mode: Check out the Table of Contents before editing if you are using manual check-out

If you are using manual check-out the Table of Contents is protected against simultaneous editing by multiple users. To make any changes (new topic, delete topic, move topic, edit topic caption) you will need to check out the Table of Contents:

1.Select the Table of Contents heading in the Project Explorer.

2.Select Project > Manage Topics > File > Check out or right click on the topic in the Project Explorer and select Version Control System > Check Out in the context menu.

The Table of Contents header will be marked with a green "checked out" icon and will be locked for other users. When you have finished editing save your project and check the TOC back in again.

See the chapter on Multi-User Editing for more details on this.

The situation here is the same as for for the Table of Contents. Unlike topics, your project's configuration settings cannot be checked out and locked for exclusive editing. All users working on the project are able to make changes the settings in the Configuration section in the Project Explorer. If two users make conflicting changes the last one who saves their project will get a conflict resolution dialog asking them to decide if they want to keep their own changes or the changes made by the previous user.

Always select Refresh Project before editing project settings!

If you know that other users may be working on the same project you should always save your project and select Refresh Project in the Project tab to make sure that your local copy is updated with any recent changes made by other users. Then you can confidently make your own changes, after which you should always save immediately to commit your changes to the VCS database.

Assign one team member to be responsible for project settings

The best approach here is to assign one member of your team to be responsible for making changes in the project configuration. If anyone needs a change they should ask this team member to make it instead of making it themselves. This will guarantee that you never have conflicts.