Branches and pull requests let you change content in a separate workspace instead of editing the original chapter directly, and then apply the changes to the original chapter after review.

A branch is a workspace created from a specific chapter. Changes you make in a branch do not immediately change the original chapter. A pull request is the process of asking for the work done in a branch to be applied to the original chapter.

Branches

A branch is an independent workspace created by copying the original chapter. In a branch, you can do the following with the same editor as the regular editing screen.

• Edit the chapter title

• Edit paragraph content

• Add paragraphs

• Delete paragraphs

• Move paragraphs

• Change the paragraph type, alias, and options

The branch list shows the branch name, status, original chapter, open pull request, creator, creation time, and last modified time. The status is shown as follows.

Creating a Branch

Document owners and collaborators can create branches. Create a branch as follows.

1. On the document details screen, click the <1Branch> link.

2. Click the <2Create Branch> link.

3. Enter a branch name.

4. Select the chapter to work on.

   • If you leave the branch name empty, it is filled in with the title of the selected chapter.

5. Click the Save button.

When you create a branch, a separate workspace is created from the selected chapter. Changes you make in this workspace are not applied to the original chapter until you create and merge a pull request.

Working in a Branch

Click a branch name to go to the branch screen.

Checking Changes

In the “Compare” panel on the branch screen, click the <View> link to see the changes between the current branch and the original chapter.

The changes screen shows the differences between the original and the branch in the context of the whole chapter. Instead of listing only the changed paragraphs, it shows the entire chapter content and marks the changed parts.

Use the 1<Up> and <Down> links to move between changes. Click the <Refresh> link to reload the changes. At each change, you can see what was changed.

• Chapter title changed

• Paragraph content changed

• Paragraph type changed

• Paragraph alias changed

• Paragraph options changed

• Paragraph added

• Paragraph deleted

• Paragraph moved

Pull Requests

A pull request is a request to apply the changes in a branch to the original chapter. Reviewers check the changes on the pull request screen and can merge or close the pull request.

When you create a pull request, the branch content at that time is saved as the basis for review. Changes you make in the branch afterward are not included in a pull request that has already been created.

The pull request list shows the pull request title, branch, status, original chapter, creator, creation time, and last modified time.

The status is shown as follows.

Creating a Pull Request

1. Go to the branch screen.

2. Click the <Create Pull Request> link.

   • The link appears only when the branch is in the DRAFT status.

3. Enter a title and description.

4. Click the Save button.

When the pull request is created, the branch changes to the OPEN_PR status. In this status, you cannot create another pull request from the same branch.

Reviewing a Pull Request

On the pull request screen, you review the changes in the context of the original chapter, based on the branch snapshot taken when the pull request was created. While the branch screen shows changes based on the current state of the branch, a pull request review covers the content fixed at the time of creation.

Reviewers check the following.

• Which paragraphs were added

• Which paragraphs were deleted

• Which paragraphs were moved

• How the content, type, alias, and options of paragraphs changed

• Whether the original chapter changed after the pull request was created, causing conflicts

Changes made in the original chapter are shown with “Source” in front of the edit history entry. Paragraph and title changes in the original chapter are shown in a different color from changes made in the branch, so you can tell them apart even when one paragraph has changes from both sides.

If necessary, you can leave comments to exchange feedback with the author.

Resolving Conflicts

If the original chapter changes after a pull request is created, conflicts can occur. Paragraphs with conflicts are shown separately on the review screen. For each paragraph, the reviewer selects one of the following.

If there are conflicts, select how to resolve every conflicting paragraph before you merge. You cannot merge while any conflict is unresolved.

Merging

Merging applies the changes in a pull request to the original chapter. Only document owners can merge pull requests.

1. Review the changes on the pull request screen.

2. If there are conflicts, select how to resolve each paragraph.

3. Click the <Merge> link.

4. In the “Are you sure you want to merge this pull request?” message, click the OK button.

   • When the merge is complete, the changes are applied to the original chapter.

A merge is based on the branch snapshot taken when the pull request was created, and applies to the original chapter only the paragraphs and order that were actually changed in the branch. Paragraphs that were edited or moved only in the original chapter after the branch was created remain as they are. The work history of the branch itself is not brought into the original chapter.

Merged pull requests remain as records. You cannot merge a pull request that has already been merged. When the merge is complete, a notification is sent to all document owners and to document collaborators who watch the document and allow notifications.

Closing and Deleting

If you do not want to apply a pull request to the original chapter, click the <Close> link on the pull request screen. Document owners and the user who created the pull request can close it. If the user who created the pull request closes it, a notification is sent to the document owners. If another user closes it, a notification is sent to the user who created the pull request. When a pull request is closed, the branch returns to the DRAFT status, and you can create a new pull request.

Document owners and the user who created the pull request can delete it with the <Delete> link on the pull request screen.

The user who created a branch can delete it with the <Delete> link on the branch screen. You cannot delete a branch that has an open pull request. After the pull request is closed or merged, you can delete the branch. Records of closed or merged pull requests remain even after you delete the branch.

If you delete the original document, the branches and pull requests created from it are also deleted.

Tips

• Keep branches small. Review and merge are easier when each branch covers only one topic of change.

• Check the changes on the branch screen before you create a pull request. It is a good idea to also check changes that are easy to miss, such as moved or deleted paragraphs and changed options.

• If the original chapter changes often, review and merge pull requests quickly instead of leaving them open for a long time.