documentationbible2018 sourcecontrol · contents chapter1 introduction 4 ourprojects 5...

USER GUIDE

DOCUMENTATION BIBLE 2018

Source Control

Copyright 2018 MadCap Software. All rights reserved.

Information in this document is subject to change without notice. The software described in this document is fur-nished under a license agreement or nondisclosure agreement. The software may be used or copied only in accord-ance with the terms of those agreements. No part of this publication may be reproduced, stored in a retrieval system,or transmitted in any form or any means electronic or mechanical, including photocopying and recording for any pur-pose other than the purchaser's personal use without the written permission of MadCap Software.

MadCap Software7777 Fay AvenueLa Jolla, California 92037858-320-0387www.madcapsoftware.com

THIS PDF WAS CREATED USING MADCAP FLARE.

CONTENTS

CHAPTER 1

Introduction 4Our Projects 5How We Use Source Control 7Tasks and Procedures 8

CHAPTER 2

How We Use Source Control 9Branches 10Before We Begin 12Best Practices and Rules 13How It Works 15

CHAPTER 3

Tasks and Procedures 25Daily Tasks 26Occasional Tasks 68

CONTENTS iii

CHAPTER 1

IntroductionSource control is essential for us to work efficiently as a team and to keep different iterations of doc-umentation organized.

This chapter discusses the following:

Our Projects 5

How We Use Source Control 7

Tasks and Procedures 8

CHAPTER 1 4

Our ProjectsBecause we have a few different types of projects, the way source control is used varies:

n Shared Project—Dual-Bound For the main Shared project, we use a dual-bound source controlstructure. The primary source control binding is with Git, and we use Visual Studio as the inter-face to manage our files. Also, we work with branches to enable the smoothest agile workflowpossible. With writers working mostly in their own branches, the chances for conflicts andother issues are reduced. This system also means we don’t need to keep multiple copies ofprojects over time. Instead, we can simply retrieve files from a certain point in time and cre-ate a new branch if necessary if we need to make changes to a previously released output.

The Shared project is also bound to Central, so that is our secondary binding. Most of thework is done with the primary Git binding, but when we want to build and publish output, wepush the updated files to Central.

n Documentation Bible and “Develop” Projects—Single-Bound The Documentation Bible and our“Develop” projects all retrieve files from the Shared project via Global Project Linking.However, unlike the Shared project, these other projects have only one source control bindingto Central. So we do not use Visual Studio for managing our source control activity in theseprojects. Instead, we simply commit our changes and then synchronize the projects with theirclones on Central. We do this because we are not concerned with branching in the Docu-mentation Bible and “Develop” projects, so we use the simpler setup.

CHAPTER 1 5

CHAPTER 1 6

How We Use Source ControlSee the following (preferably in order) for more details on different concepts and how we usesource control:

n "Branches" on page 10

n "Before We Begin" on page 12

n "Best Practices and Rules" on page 13

n "How It Works" on page 15

CHAPTER 1 7

Tasks and ProceduresSee the following for details on the various tasks that we perform with source control:

n "Daily Tasks" on page 26

n "Occasional Tasks" on page 68

n Step-by-Step Procedures:

l "Opening the Shared Repository" on page 28

l "Viewing Branches" on page 29

l "Creating Branches" on page 69

l "Retrieving Branches" on page 74

l "Checking Out Branches" on page 32

l "Pulling Commits" on page 34

l "Committing and Pushing Changes" on page 59

l "Merging from Release to a Feature Branch" on page 35

l "Merging from Release to the Develop Branch" on page 43

l "Merging from a Feature Branch to the Develop Branch" on page 51

l "Merging from a Feature Branch to the Release Branch" on page 77

l "Merging from Release to the Master Branch" on page 86

l "Deleting Old Feature Branches" on page 94

l "Dealing with Issues, Conflicts, and Messages" on page 95

l "Reverting Branches" on page 118

l "Using Hot Fixes to Update Old Outputs" on page 122

CHAPTER 1 8

CHAPTER 2

HowWe Use Source ControlYou should become quite familiar with different concepts and the way that we use source controlon the MadCap Documentation Team.


Branches 10

Before We Begin 12

Best Practices and Rules 13

How It Works 15

CHAPTER 2 9

BranchesOur source control process is based on a method called “Gitflow”:

https://datasift.github.io/gitflow/IntroducingGitFlow.html

This system allows for continuous, parallel development and collaboration through the use ofbranches. However, ours is a somewhat simplified version of the Gitflow system, and we’ve tailoredit just for our needs.

A branch is not an entirely separate copy of a Flare project. Rather, it is the same project but withchanges recorded independently of the other branches. So one person could be documenting a cer-tain feature in one branch while another writer documents a different feature in a second branch.Then at some point, documentation from each of those branches could be merged into yet anotherbranch. But you’re still working in the same project.

In our process, there are following types of branches:

n Master This is the current version of the documentation, whose output is available to endusers. This branch is typically ignored until the very end of a release cycle. Unlike the othertypes of branches, most writers should not be merging changes into the master branch at all.Only one writer should be assigned to merge changes to the master branch when the time isright.

n Release This is the next version of the documentation. It holds changes from finished featurebranches as development progresses. Each writer merges changes from his or her featurebranch to the local release branch when the documentation for that feature is ready and it isassured the feature will be included in the next release, rather than backlogged. Typically, wewait for the programmers to move the feature into their release branch before we move thedocumentation into our release branch.

n Feature There are multiple feature branches, and they are created as necessary. This iswhere the bulk of the actual work is done. Changes in feature branchesmay become part ofthe next version of the documentation (i.e., the release branch) or they might be held backanother product release sometime in the future. Also, we organize our feature branchesaccording to the product (e.g., Flare, Capture, Lingo) or under the banner of “Global” (if thechanges pertain to multiple products). Each product will have a “whats-new” branch for doc-umenting the “What’s New” topic, but most of the other branches are named after a particularfeature.

n Develop This branch is sort of a sandbox that is a consolidation of other branches as they arebeing developed. The main purpose for this branch is that it allows us to import these filesthat are in progress into a child “Develop” project. The changes in the “Develop” project arethen pushed up to Central. From there, we can create and manage checklists to track the

CHAPTER 2 10

https://datasift.github.io/gitflow/IntroducingGitFlow.html

progress of files for a given release cycle. We can also send topics from these child projectsfor review on Central. In addition to merging individual feature branches into the developbranch as necessary, writers can also merge the release branch into the develop branch peri-odically to get the latest files.

CHAPTER 2 11

Before We BeginHere are a few things to know before you delve into the source control process:

n Visual Studio 2017 We create and manage branches in Visual Studio 2017, so you need tohave that installed and connected to our Shared repository.

n Understand Commits A commit allows you to add your local changes in Flare to the local Gitdatabase; you can later push those changes to the remote repository. So a commit is really acollection of your changes, and you decide what goes into that commit. Sometimes you mighthave a group of unrelated changes that get added to the same commit. But it is preferablethat you try to work on logical chunks of content, consolidate them into a single commit, add acomment to the commit that best describes those changes, and then push that commit tothe remote repository. Doing it this way helps us identify certain changes that we might haveto pull out of a branch later if necessary.

Also, when you delete files in a Flare project, Git will count those deletions as separate com-mits.

n Remote and Local Branches There are remote branches that can be accessed by all writers,and there are local versions of branches as needed by each user (e.g., there might be aremote version of a feature branch called “style-editor” and a local version of the same nameon a writer’s computer). One writer might have some local feature branches, whereasanother writer might have entirely different feature branches. It all depends on who is workingon what.

n Moving Changes between Branches Changes in a branch can be moved (i.e., pulled andpushed) between remote and local versions of the same branch. Changes can also be moved(i.e., merged) from one branch name to another (e.g., merge changes from a feature branchinto the release branch). Theoretically, any branch could be merged with any other branch.But in practice, we want to maintain rules as to which branches should be merged with which,when, and by whom. Merging is typically done between local branches (e.g., merging from thelocal release branch into the local feature branch), and then the resulting commits are pushedfrom the local branch up to the remote branch.

n Focus on Daily Tasks There is a lot of information on our source control process to absorb,and it might not all make complete sense immediately. That’s okay. As you work in this sys-tem, it will become more familiar over time. Also, keep in mind that some of this contentneeds to be applied only occasionally. Although you should read this source control doc-umentation in its entirety, it is recommended that you mostly focus at first on the tasks thatyou need to do every day. See "Daily Tasks" on page 26.

CHAPTER 2 12

Best Practices and RulesFollowing are a few important best practices and rules to keep in mind as you work with this sourcecontrol system:

n Work in Correct Branch When a branch is checked out (i.e., selected), Flare will automaticallyadjust to show only the changes that are part of that branch. If you check out a differentbranch, Flare will adjust again. There isn’t anything special you need to do, but it is importantto always look at which branch is selected in Visual Studio before you begin making a lot ofchanges in Flare. See "Checking Out Branches" on page 32.

n Pull Then Commit/Push One of the most important rules when dealing with branches in Git isto always do a pull from the remote branch before you commit and push files. This helps keepthings in sync better and results in a cleaner history. In other words, every time you check outa branch, you should immediately do a pull; there’s no downside to doing a pull and lots ofupside. See "Pulling Commits" on page 34 and "Committing and Pushing Changes" on page 59.

n Sync Release Branches Although most of your work is done within feature branches, you alsowill need to pull changes every day from the remote release branch into your local releasebranch. And when the time comes toward the end of the release cycle that you mergechanges to the local release branch, you’ll also need to push those changes up to the remoterelease branch. See "Pulling Commits" on page 34 and "Committing and Pushing Changes" onpage 59.

n Merge between Release and Feature Branches Merging from a feature branch to the releasebranch should only be done when you are confident the documentation is ready and the featurewill definitely be included in the next product release. See "Merging from a Feature Branch tothe Release Branch" on page 77.

Merging from the release branch to feature branches should be done daily. That’s becauseother writers might have finished working on some of their feature branches and mergedthem into the release branch, and you want to make sure you integrate those changes intothe feature branches you are working on. Doing this regularly will help offset potential issuesthat could arise. The longer you wait between merges, the greater the chance for file con-flicts, especially those where it becomes hard to remember exactly what you did in particularfile. See "Merging from Release to a Feature Branch" on page 35.

n Never Merge from Develop There is a lot of merging happening in both directions between dif-ferent branches. This includesmerging the release and feature branches into the developbranch regularly. But one thing you should never do is merge from the develop branch intoany other branch. The develop branch contains content from branches that may or may not

CHAPTER 2 13

be included in the upcoming product release, and we don’t want that content to accidentallyend up in the release or master branches.

n One Person Merging to Master Everyone should be synchronizing local and remote branches,and everyone should be merging to and from the release branch (when appropriate). But onlyone person should merge from the release branch into the master branch when we are readyto build and publish the final output for a product release. See "Merging from Release to theMaster Branch" on page 86.

n Delete Old Branches Over time, there can be tons of feature branches. But many of themsoon become obsolete because they were used only for a particular release cycle. So after afinal product release and merge to the master, those old branches should be deleted. It is alsoa good idea to periodically delete the develop branch and create a new one to keep it fresh.See "Deleting Old Feature Branches" on page 94.

CHAPTER 2 14

How It WorksFollowing is a mostly sequential look at how the overall source control process works.

Create and Check Out BranchesWhen you want to document a new feature for a product, or make certain global changes thataffect multiple products, you create a new feature branch that is based on the release branch (see"Creating Branches" on page 69). If the branch already exists, you simply check it out (see "CheckingOut Branches" on page 32). Then in Flare, work in that branch, documenting your changes like younormally would.

CHAPTER 2 15

Pull from Remote BranchWhenever you check out an existing branch, you should immediately pull from the remote branch.See "Pulling Commits" on page 34.

CommitAnytime you commit your work in a branch (see "Committing and Pushing Changes" on page 59), anew record of those changes is recorded (represented by dots in the following graphic). A commitalso occurs when you merge from branch to another.

CHAPTER 2 16

Push to Remote BranchAfter you commit changes, you push those changes from the local to the remote branch. See "Com-mitting and Pushing Changes" on page 59.

Merge from Feature to ReleaseWhen you are finished documenting in a feature branch (i.e., you consider it ready for final pub-lication), you merge that branch into the release branch. See "Merging from a Feature Branch to theRelease Branch" on page 77.

CHAPTER 2 17

Merge from Release to FeatureEvery day, you should merge from the release branch into your ongoing feature branches (see "Mer-ging from Release to a Feature Branch" on page 35). This ensures that changes from finished fea-ture branches are integrated into the ongoing feature branches.

CHAPTER 2 18

Work with Develop BranchThere is one more special kind of branch called develop that you will use during a release cycle. Themain purposes of this branch are:

n It lets us work with checklists in Central for topics that are in development.

n It lets others review our topics that are in development.

n It lets us run reports on files that are in development and specific to a particular product.

n It lets us send internal output that is in development to others for preview.

n It lets us see how various new files from various branches integrate with one another duringdevelopment.

BASICS OF THE DEVELOP BRANCH

Although we do have our main Shared project bound to Central (for building and publishing pur-poses), it is the master branch only that is represented in that cloned project. That’s because Cen-tral currently does not support branching, and only the master branch can be pushed up to Central.This means that you do not have access to the newest files and changes when looking at that pro-ject in Central.

When it comes to the tasks mentioned above (e.g., creating checklists, sending topics for review),we want to have access to new and updated files as the release cycle progresses. Therefore, wecreate child products for each product, naming them with the word “Develop” (e.g., Flare - Develop,Central - Develop, Lingo - Develop).

We check out the develop branch for the Shared project (see "Checking Out Branches" on page 32).Then we open a child “Develop” project and use Global Project Linking to import the files pertinent tothat product (e.g., Flare, Central, Lingo). Within Flare (not Visual Studio), we do a commit and pushthe changes in the child project up to Central. From Central, we can then work on things such aschecklists and reviews based on files in the develop branch.

CHAPTER 2 19

GITFLOW AND THE DEVELOP BRANCH

So how does the develop branch fit in with the Gitflow system? When you need to update files inCentral for one of the purposes previously mentioned (e.g., creating checklists, sending topics forreview), here is what you will need to do…

If the develop branch already exists remotely, but you don’t have it locally yet, retrieve it. See"Retrieving Branches" on page 74.

To make sure you have all of the latest files, merge changes from the release branch, as well asfrom each feature branch you need, into the develop branch. See "Merging from Release to theDevelop Branch" on page 43 and "Merging from a Feature Branch to the Develop Branch" on page51.

CHAPTER 2 20

Ideally, this is something that should be done daily during a release cycle. See "Daily Tasks" on page26.

Next, push your changes from the local copy of the develop branch up to the remote developbranch (see "Committing and Pushing Changes" on page 59).

This way, others can pull those same files to their local develop branch.

With the develop branch checked out for the Shared project, you can open one of the child“Develop” Flare projects and re-import Shared files into it. It is important to first make sure the

CHAPTER 2 21

develop branch is checked out, because the child project will import files from whatever branch youhave opened. If you mistakenly have another branch checked out, you probably won’t be importingall of the files that you actually need.

After you’ve imported the files into the child “Develop” project, push the changes up to Central (thispush is done from the Central window pane within Flare, not within Visual Studio). Then you canwork with checklist(s), reviews, etc.

The develop branch is much like a sandbox. It’s not going to be used to do any work that will be partof the actual release, and it’s certainly not used for the final output. It’s really there to help you trackthe progress of files during a release cycle and perform other “in development” chores. This meansthat the develop branch can be deleted anytime you like. After all, it can always be easily re-createdlater when you need to use it again.

CHAPTER 2 22

Merge from Release to MasterAfter all the feature branches that are part of the release cycle are completed and merged into therelease branch, any final work (additional documentation, fixes, cleanup) can be done directly in therelease branch until we are satisfied that everything is okay. At that point, one person merges therelease branch into the master (see "Merging from Release to the Master Branch" on page 86). Also,the release branch is merged into other feature branches that are not part of this release cycle, butwill be finished in the future (see "Merging from Release to a Feature Branch" on page 35).

CHAPTER 2 23

Delete Old BranchesA few days after the product release, the feature branches no longer used are deleted, leaving onlyfeature branches that are still in development. We usually coordinate this so that each writer isdeleting the necessary branches both locally and remotely. See "Deleting Old Feature Branches" onpage 94.

CHAPTER 2 24

CHAPTER 3

Tasks and ProceduresThere are various tasks that we perform with source control. Some of these should be done daily (orat least frequently) and others are more occasional.


Daily Tasks 26

Occasional Tasks 68

CHAPTER 3 25

Daily TasksIf there is one section of this source control documentation that is the most important for you tointernalize, this is it. Following are tasks that you should do every day, in order. You should printthese steps and pin them on your wall for reference, until they become second nature. If everyoneon the team follows these steps consistently, we should be able to limit any conflicts or issues thatmight arise.

Sync Release Branches1. Open the repository (see "Opening the Shared Repository" on page 28) and view the branches

in Team Explorer (see "Viewing Branches" on page 29).

2. Check out the local release branch. See "Checking Out Branches" on page 32.

3. Pull commits from the remote release branch into the local release branch. See "Pulling Com-mits" on page 34.

Sync Feature Branches and Merge from Release1. Check out a local feature branch. See "Checking Out Branches" on page 32.

2. Pull commits from the remote feature branch into that local feature branch. See "Pulling Com-mits" on page 34.

3. Merge the local release branch into that local feature branch. See "Merging from Release to aFeature Branch" on page 35.

4. Repeat these steps for each local feature branch that you have (it shouldn’t be too many; if itis, you have probably been assigned to too many feature branches, or you have some old onesthat need to be deleted).

CHAPTER 3 26

Sync Develop Branch and Merge from Release/Feature1. Check out the local develop branch. See "Checking Out Branches" on page 32.

2. Pull commits from the remote develop branch into the local develop branch. See "Pulling Com-mits" on page 34.

3. Merge the local release branch into the local develop branch. See "Merging from Release tothe Develop Branch" on page 43.

4. Merge each of your local feature branches into the local develop branch. See "Merging from aFeature Branch to the Develop Branch" on page 51.

Work in Feature Branch1. Check out a local feature branch to work in it. "Checking Out Branches" on page 32.

2. Pull commits from the remote feature branch into that local feature branch. See "Pulling Com-mits" on page 34.

3. Work as usual in Flare, and commit your changes at logical breaks throughout your work day.Make sure to add a comment to your commits. Then push your commits to the remote fea-ture branch. See "Committing and Pushing Changes" on page 59.

You should not have any outgoing commits at the end of the day. Everything should bepushed to the remote branches.

IMPORTANT: You should nevermerge the develop branch into any other branches. Thedevelop branch only receives commits from other branches; it should not send them out.

When you perform Git tasks, you are likely to encounter certain issues, conflicts, and messagesfrom time to time. For details on addressing the most common problems, see "Dealing with Issues,Conflicts, and Messages" on page 95.

CHAPTER 3 27

Opening the Shared RepositoryBefore you perform any source control task, you must first open the Shared repository.

HOW TO OPEN THE SHARED REPOSITORY

1. Open Visual Studio 2017.

2. In the Team Explorer, double-click Shared (the name of the repository for our main “Shared”project).

CHAPTER 3 28

Viewing BranchesTo see all of the branches in your repository and take different actions on them, open the Branchesview of the Team Explorer.

HOW TO VIEW BRANCHES

1. At the top of the Team Explorer, click . The Home view of the Team Explorer opens.

2. Click Branches.

CHAPTER 3 29

Local branches are listed at the top, and remote branches are listed under remotes > origin atthe bottom. You will be checking out local branches only, and then pulling and pushingchanges from and to the remote branches as necessary.

CHAPTER 3 30

NOTE: Your folder might say “remotes/origin” instead. The MadCapCentral folderseen in the image above is due to the master branch being pushed up to our Centrallicense. But if you have not pushed this branch to Central (and most people on theteam won’t), you will not see this folder.

CHAPTER 3 31

Checking Out BranchesWhen you want to work in a branch, you need to first check it out.

HOW TO CHECK OUT A BRANCH

1. Open the Branches view in the Team Explorer. See "Viewing Branches" on page 29.

2. Double-click a local branch that you want to check out. You will know that it is the activebranch because it appears in bold in the Team Explorer and also displays in the status bar atthe bottom.

CHAPTER 3 32

If you have the Shared project open in Flare, you will see the files and edits pertaining to thatbranch. When you switch to a different branch in Visual Studio, the Flare project will auto-matically change to show files and edits for that branch. In other words, you do not have mul-tiple copies of the Flare project for each branch, but rather when you switch from branch tobranch, only the files and changes that are current in the active branch are shown.

For example, let’s say you have a branch called “style-editor” and another called “fixed-head-ers.” If you have the style-editor branch selected, you will see the entire Shared project and allits files, but you will also see the files and edits that are unique to that branch. You won’t seeany of the edits from the “fixed-headers” branch, and someone working in that branch won’tsee your style-editor changes. At least not yet.

TIP: It is sometimes a good idea to close a project in Flare before checking out a differentbranch. The more changes there are between branches, the more time it might take forFlare to reload the new branch.

CHAPTER 3 33

Pulling CommitsAs a general rule, perform this step immediately after you check out a branch.

HOW TO PULL COMMITS

1. After you have checked out a branch, you should see it listed in bold in the Team Explorer.Right-click the branch.

2. From the context menu, click Pull.

CHAPTER 3 34

Merging from Release to a Feature BranchDo this every day for each feature branch that you have locally. You should only have featurebranches that you will be working on. Another writer will probably have different feature branchesthan you have. If you still have old branches from a previous release cycle, you should delete thoseso that you are not unnecessarily merging into them every day (see "Deleting Old Feature Branches"on page 94).

HOW TO MERGE FROM RELEASE TO A FEATURE BRANCH


2. Double-click the feature branch to check it out.

CHAPTER 3 35

The name should be in bold and you should also see it at the bottom of the interface.

CHAPTER 3 36

3. Right-click the branch and select Merge From.

CHAPTER 3 37

4. In the Merge from branch field, select release (the local branch).

The feature branch should already be selected in the bottom field.

CHAPTER 3 38

5. Click Merge.

CHAPTER 3 39

You will see a number next to the arrow at the bottom of the interface. That’s because youhave merged the release branch with the local copy of the feature branch, but now you haveto push those changes from the local feature branch up to the remote feature branch.

CHAPTER 3 40

6. Click this number. The Team Explorer displays the Synchronization view, showing all commitsthat need to be pushed.

CHAPTER 3 41

7. Click Push.

CHAPTER 3 42

Merging from Release to the Develop BranchDo this every day for the local develop branch.

HOW TO MERGE FROM RELEASE TO THE DEVELOP BRANCH


2. Double-click the develop branch to check it out.

CHAPTER 3 43


CHAPTER 3 44

3. Right-click the branch and select Merge From.

CHAPTER 3 45

4. In the Merge from branch field, select release (the local branch).

The feature branch should already be selected in the bottom field.

CHAPTER 3 46

5. Click Merge.

CHAPTER 3 47

You will see a number next to the arrow at the bottom of the interface. That’s because youhave merged the release branch with the local copy of the develop branch, but now you haveto push those changes from the local develop branch up to the remote develop branch.

CHAPTER 3 48


CHAPTER 3 49

7. Click Push.

CHAPTER 3 50

Merging from a Feature Branch to the Develop BranchEvery day you should merge each of your local feature branches into the local develop branch.

HOW TO MERGE FROM A FEATURE BRANCH TO THE DEVELOP BRANCH


2. Double-click the local develop branch to select it.

CHAPTER 3 51


CHAPTER 3 52

3. Click Merge.

CHAPTER 3 53

4. In the Merge from branch field, select your feature branch.

The develop branch should already be selected in the bottom field.

CHAPTER 3 54

5. Click Merge.

CHAPTER 3 55

You will see a number next to the arrow at the bottom of the interface. That’s because youhave merged your feature branch with the local copy of the develop branch, but now you haveto push those changes from the local develop branch up to the remote develop branch.

CHAPTER 3 56


CHAPTER 3 57

7. Click Push.

The remote develop branch now has the latest changes for that feature branch.

CHAPTER 3 58

Committing and Pushing ChangesCommitting changesmeans to tell Git that your edits are ready to be moved from the local branchup to the remote branch. You might work all day and not commit your changes until just before yougo home (not recommended though). Other times, you might commit changes several times a day.Because each commit is accompanied by a comment that you write, you might decide to perform acommit whenever you come to a natural break in your work. By separating work into multiple com-mits, it can be easier to access or undo those changes later on if it becomes necessary, without dis-turbing the other changes.

EXAMPLE

You might have documented three particular topics all morning and need to switch toworking on the glossary. So if you want the topic work to be included in a separate “con-tainer,” you can commit those changes with a comment that identifies those three top-ics. Then you can work on the glossary for a while and do another commit, with acomment related to that work. And you might finish up your day by working on a coupleof different topics, then committing those changes with a comment pertaining to thework you did.

CHAPTER 3 59

HOW TO COMMIT AND PUSH CHANGES

1. Check out the local branch and work in Flare as you normally would. See "Checking OutBranches" on page 32.

2. When you want to commit changes, look at the bottom of the Visual Studio user interface.Next to the pencil icon, you will see a number indicating how many files with uncommittedchanges you have in your project.

CHAPTER 3 60

3. Click the number. The Team Explorer displays the Changes view, showing the uncommittedfiles.

CHAPTER 3 61

4. Enter a comment related to your changes. The comment should start with the name of theproduct (e.g., Central, D2H, Flare) or “Global” (if the changes affect multiple products), fol-lowed by a hyphen and then your comment.

CHAPTER 3 62

5. Click Commit All.

CHAPTER 3 63

You should now see a number next to the up arrow at the bottom of the user interface. Thisindicates the number of commits that still need to be pushed up to the remote branch.

CHAPTER 3 64

6. Click this number.

The Team Explorer switches to the Synchronization view. This shows your outgoing commits,as well as any incoming commits that might also be available.

CHAPTER 3 65

7. Click Push. Alternatively, you can click Sync to both pull any remote commits and push yourlocal commits.

CHAPTER 3 66

NOTE: Files changes are treated as one commit, while a deleted file is treated as a sep-arate commit.

CHAPTER 3 67

Occasional TasksFollowing are tasks that should be performed only as needed:

n Create Branch Create a new feature branch (based on the release branch) when there is anew feature for a product that you need to start documenting. You can also create newbranches for general documentation changes (for a specific product or globally for multipleproducts). See "Creating Branches" on the next page.

n Retrieve Branch If a branch exists remotely but you do not yet have it locally on your com-puter, you need to retrieve it if you want to work in it. See "Retrieving Branches" on page 74.

n Merge Feature Branch into Release When you are finished documenting in a feature branchand believe it is ready for final publication, merge that feature branch into the release branch.Typically, we wait for the programmers to move the feature into their release branch beforewe move the documentation into our release branch. See "Merging from a Feature Branch tothe Release Branch" on page 77.

n Merge Release Branch into Master When all of the documentation is completed and ready forfinal publication, one person merges the release branch into the master branch. See "Mergingfrom Release to the Master Branch" on page 86.

n Delete Old Branches A few days after the product release, you can delete the old featurebranches that are no longer needed. See "Deleting Old Feature Branches" on page 94.

n Deal with Issues, Conflicts, and MessagesWhen you perform Git tasks, you are likely toencounter certain issues, conflicts, and messages from time to time. Some of these can besolved by following certain steps in Visual Studio. Others need to be resolved using the com-mand line. See "Dealing with Issues, Conflicts, and Messages" on page 95.

n Revert Branches This would only be necessary if we merge something into the release branchbut then are told the feature won’t be included in that release of the product after all, or if weaccidentally merge into the wrong branch. So we need to revert that branch, backing thosechanges out. See "Reverting Branches" on page 118.

n Use Hot Fixes to Update Outputs If we need to fix published output for an older release, wecan create a branch for it off the appropriate place in the master. Then make the changesand republish. See "Using Hot Fixes to Update Old Outputs" on page 122.

CHAPTER 3 68

Creating BranchesThe following steps show how to create a new branch, which can be done for any type of branch,but it is done most often for new feature branches.

HOW TO CREATE A BRANCH


2. Double-click the local release branch so that it is bold.

3. Right-click the release branch and select New Local Branch From.

CHAPTER 3 69

4. In the area at the top of the Team Explorer, enter a name for the new branch. When doing this,adhere to the following standards:

n Start with the name of the product (e.g., Central, D2H, Flare) or the word “Global” if thenew branch applies to multiple products. Follow this with a forward slash and then thename of the new branch.

n User lowercase for the names of branches.

n For branches with multiple words, separate them with hyphens.

CHAPTER 3 70

5. Click Create Branch.

CHAPTER 3 71

6. The branch now exists locally, but still needs to be pushed so that it has a remote counterpartthat is available to you and other writers. To do this, right-click the new branch and selectPush Branch.

CHAPTER 3 72

That branch can now be seen with the other remote branches in the Team Explorer.

CHAPTER 3 73

Retrieving BranchesIf a branch exists remotely but you do not yet have it locally on your computer, you need to retrieveit if you want to work in it.

HOW TO RETRIEVE A BRANCH


2. Expand the remotes > origin section.

CHAPTER 3 74

3. In the remotes > origin section, double-click the branch you want to retrieve.

CHAPTER 3 75

The branch now displays with the local branches in the upper portion of the Team Explorer.

CHAPTER 3 76

Merging from a Feature Branch to the Release BranchWhen you are all finished documenting in a branch for the next release, you are ready to merge thatfeature branch to the release branch. You do not want to do this too soon, because there might beadditional (or different) documentation that becomes necessary as the product release date nears.Also, the decision might be made to pull that feature out of the release, saving it for a later release.However, you also don’t want to wait too long to perform this step, because other branchesmay bedependent on the changes from your branch, or you might need the extra time to resolve any poten-tial conflicts that might arise. But when you are fairly confident in the completeness of the doc-umentation and in its inclusion in the next release, you need to merge that branch to the releasebranch. Typically, we wait for the programmers to move the feature into their release branch beforewe move the documentation into our release branch.

HOW TO MERGE FROM A FEATURE BRANCH TO THE RELEASE BRANCH


2. Double-click the local release branch to select it.

CHAPTER 3 77


CHAPTER 3 78

3. Click Merge.

CHAPTER 3 79

4. In the Merge from branch field, select your feature branch.

The release branch should already be selected in the bottom field.

CHAPTER 3 80

5. Click Merge.

CHAPTER 3 81

You will see a number next to the arrow at the bottom of the interface. That’s because youhave merged your feature branch with the local copy of the release branch, but now you haveto push those changes from the local release branch up to the remote release branch.

CHAPTER 3 82


CHAPTER 3 83

7. Click Push.

CHAPTER 3 84

The remote release branch now has the latest changes for that feature branch. You shouldnot need to open and work in that feature branch again, unless additional documentation isrequired. In that case, you would need to repeat these steps to merge to the release branchagain.

NOTE: If you merge a feature branch to the release branch and then are informed the fea-ture will not be included in the next version of the product, you will need to revert thebranch. See "Reverting Branches" on page 118.

CHAPTER 3 85

Merging from Release to the Master BranchOnly one person will merge the release branch into the master branch when all of the doc-umentation is ready for a final build and publication.

HOW TO MERGE FROM RELEASE TO THE MASTER BRANCH

1. Ensure that all relevant feature branches have been merged into the release branch. See"Merging from a Feature Branch to the Release Branch" on page 77.

2. Ensure that the local release branch has been synchronized with the remote release branch.


4. Double-click the master branch to select it.

CHAPTER 3 86


CHAPTER 3 87

5. Click Merge.

CHAPTER 3 88

6. In the Merge from branch field, select the local release branch.

The master branch should already be selected in the bottom field.

CHAPTER 3 89

7. Click Merge.

CHAPTER 3 90

You will see a number next to the arrow at the bottom of the interface. That’s because youhave merged the release branch with the local copy of the master branch, but now you haveto push those changes from the localmaster branch up to the remotemaster branch.

CHAPTER 3 91


CHAPTER 3 92

9. Click Push.

The remote master branch now has the latest changes. With the master branch checked out,you can open the project in Flare and build the final output(s).

CHAPTER 3 93

Deleting Old Feature BranchesA couple of days after the final product release, delete feature branches that will no longer be usedmoving forward. We usually coordinate this so that each writer is deleting the necessary branchesboth locally and remotely.

It is also a good idea to periodically delete the develop branch and create a new one.

HOW TO DELETE A BRANCH


2. Make sure the branch you want to delete is not checked out (not bold).

3. Right-click the branch you want to remove and select Delete.

NOTE: If you want to remove a branch only from your computer, just delete the localbranch. If you want to remove a branch altogether, delete both the local and remotebranches. Also, you might need to make sure any other writers also remove the branch loc-ally; otherwise, it might end up being pushed to the remote repository again.

CHAPTER 3 94

Dealing with Issues, Conflicts, and MessagesWhen you perform Git tasks, you are likely to encounter certain conflicts and messages from timeto time. Some of these can be solved by following certain steps in Visual Studio. Others need to beresolved using the command line.

Command Line

Occasionally, there are a few things that might need to be done from a command prompt instead ofthe Visual Studio or Flare interface. A few different utilities can be used for this, such as Git CMD orGit Bash. If you do not already have one of these installed, you should do so. It also might be a goodidea to pin it to your task bar for future use.

Failed to Push to Remote Repository

Sometimes Git is unable to push your commits to the remote repository. Following are a couple ofthe main reasons why this happens and steps you can take to resolve them.

REMOTE END HUNG UP (TOO MANY IMAGES)

After you attempt to push commits, you might receive an error that indicates “The remote end hungup unexpectedly.”

CHAPTER 3 95

When you see this message, chances are good that you have added more new images to a Flare pro-ject than Visual Studio can handle. As a workaround, you must push your commits using the com-mand prompt. Do the following:

1. Make sure the branch is checked out in Visual Studio. See "Checking Out Branches" on page32.

2. Open the command line utility (e.g., Git CMD).

3. At the prompt, type cd C:/Shared and press Enter.

CHAPTER 3 96

4. At the next prompt, type git push and press Enter. You should immediately see some activ-ity under the prompt.

CHAPTER 3 97

When it is finished, you should see a 0 at the bottom of the Team Explorer in Visual Studio.This means that the push worked.

CHAPTER 3 98

REMOTE CONTAINS WORK YOU DO NOT HAVE LOCALLY

After you attempt to push commits, you might receive an error that indicates “Updates were rejec-ted because the remote contains work that you do not have locally.”

CHAPTER 3 99

This means that another author has pushed commits to the remote branch that you do not haveyet. So you need to get those changes before pushing yours. Do the following:

1. Click Pull.

2. Attempt to push your commits again.

CHAPTER 3 100

Pull Completed with Conflicts

Sometimes you might attempt a pull and you see the message “Pull completed with conflicts in the‘Shared’ repository.”

This message means that the remote branch had differences in the same area of your local file. Inother words, another author made changes to the same paragraph that you did. Flare doesn’t knowwhose changes should be accepted, so you need to tell it.

Avoiding too many conflicts at the same time is one reason we try to follow our daily tasks as con-sistently as possible (see "Daily Tasks" on page 26). The more time that goes by without mergingbranches, the higher the chances for multiple conflicts. And the older the changes, the harder itbecomes to remember what exactly was done and for what purpose, and therefore more difficult todecide how to resolve it.

CHAPTER 3 101

If you encounter file conflicts, do the following:

1. Click Conflicts.

CHAPTER 3 102

All files with conflicts are listed.

2. Click on a file in the list.

3. Click Merge.

CHAPTER 3 103

The Merge Editor opens to the left, with three sections of markup for the file. The top left areashows the other authors changes, the top right area shows your changes, and the area at thebottom shows what you eventually select.

CHAPTER 3 104

4. Look for the parts of the file where a shaded piece of content is shown with empty checkboxes. These are the areas where you and the other author made conflicting changes.

CHAPTER 3 105

5. Select the check box with the change you want to accept. Your selection is automaticallyapplied to the bottom area.

CHAPTER 3 106

6. (Optional) If you want to consolidate changes from both authors, you can simply click in thearea at the bottom and type what you want.

CHAPTER 3 107

7. Click Accept Merge.

CHAPTER 3 108

8. Do this for all the conflicts in the file until none are left in the Team Explorer.

CHAPTER 3 109

9. Click Commit Merge.

CHAPTER 3 110

10. Add a comment and click Commit Staged.

CHAPTER 3 111

11. Click the number at the bottom and push the commits.

CHAPTER 3 112

Re-associating the Master Branch

Before we push commits from our master branch up to Central (using Flare), the branch looks likethis in Visual Studio:

CHAPTER 3 113

After we push commits from our master branch up to Central, the branch looks like this in Visual Stu-dio:

The branch has become associated with Central. We need to undo that change with the commandprompt.

CHAPTER 3 114

Do the following:

1. Make sure the branch is checked out in Visual Studio. See "Checking Out Branches" on page32.

2. Open the command line utility (e.g., Git CMD).

3. At the prompt, type cd C:/Shared and press Enter.

CHAPTER 3 115

4. At the next prompt, type git branch --set-upstream-to origin/master.

5. Press Enter. You should see this:

CHAPTER 3 116

And in Visual Studio, the master branch should once again look like this:

CHAPTER 3 117

Reverting BranchesReverting a branch would only be necessary if we merge something into the release branch but thenare told the feature won’t be included in that release of the product after all, or if we accidentallymerge into the wrong branch. So we need to back those changes out of the branch.

Git actually gives you the choice of resetting or reverting a branch:

n Reset The reset method is easier and cleaner, but Git recommends that you do a revertinstead. A reset means you have to go around to other writers to track down whether any ofthem have the stray commits and then have each writer reset them.

n Revert A revert makes a new commit that undoes the previous commit. One benefit is that ifother authors pulled from the branch before you backed out the commits, then those changesare out there with the other writers. A revert will undo those stray commits that other writershave out there when they pull again with the revert commit. A downside of the revert methodis that it can mess up your history a bit.

Our first choice will be to do a revert when possible.

CHAPTER 3 118

HOW TO REVERT A BRANCH


2. Double-click the branch containing the commit you want to revert.

3. Right-click the branch and select View History. The commit history opens to the left, with themost recent commit shown at the top.

CHAPTER 3 119

4. Locate the commit you want to revert, right-click it, and select Revert.

CHAPTER 3 120

5. In the message, click Yes. Notice a number displays at the bottom of the Team Explorer.

6. Click the number and push the commit.

If you view the file(s) in that branch, you will notice that the changes are no longer there, butany committed changes that were completed before or after that commit are still in the pro-ject.

CHAPTER 3 121

Using Hot Fixes to Update Old OutputsIf we need to fix published output for an older release, we can create a “hot fix” branch for it, basedon the appropriate place in the master branch. Then make the changes in Flare and republish.

HOW TO USE A HOT FIX TO UPDATE OLD OUTPUTS


2. Double-click the localmaster branch to select it.

After this, the name should be in bold and you should also see it at the bottom of the interface.

CHAPTER 3 122

3. Right-click the master branch and select View History.

CHAPTER 3 123

4. In the History window on the left, locate the most appropriate commit that you want to basethe new “hot fix” branch on. Right-click the commit row and select New Branch.

EXAMPLE

Let’s say we discover that we need to fix some text in the online Help for Doc-To-Help. So after opening the History window, we look for the most recent committhat has the D2H prefix.

Looking at the comment for that commit, we know that this was the last commitfor the most recent release. We right-click this commit in order to create the newbranch, which will be based on this commit, rather than any of the commits thatoccurred after it. This allows us to make adjustments to the project as it existedat that point in time, rather than including more recent changes that occurredsince then.

CHAPTER 3 124

5. In the area at the top of the Team Explorer on the right, enter a name for the new branch.

EXAMPLE

Continuing with the previous example, we would first enter D2H followed by a for-ward slash, and then maybe we would give it the name “hot-fix1.”

CHAPTER 3 125

Also, notice that the commit ID is already entered in the field below this, indic-ating that it will be the basis for the new branch.

6. Click Create Branch.

7. The branch now exists locally, but still needs to be pushed so that it has a remote counterpartthat is available to you and other writers. To do this, right-click the new branch and selectPush Branch.

That branch can now be seen with the other remote branches in the Team Explorer.

8. With the new “hot fix” branch checked out in the Team Explorer window, open the project andmake the necessary changes.

CHAPTER 3 126

9. When all changes from all writers are completed in that branch, make sure everything is syn-chronized (pulled, committed, pushed) for that branch.

10. Merge the “hot fix” branch into the master branch as well as the release branch.

11. Check out the master branch, then build and publish the updated output.

12. Once you are sure that the “hot fix” branch is no longer needed, you can delete both the localand remote branches. See "Deleting Old Feature Branches" on page 94.

CHAPTER 3 127

documentationbible2018 sourcecontrol · contents chapter1 introduction 4 ourprojects 5...

Documents