1. Overview

1.1 When To Use Branch And Merge Process

Branch and Merge is not necessary for the following kinds of changes 

• Spelling or grammar corrections
• Re-arranging text in a few paragraphs
• Other minor changes that take only 1 editing session to complete

Large scale changes (frequently several days or weeks to implement) include the following:

• Reorganization of large amounts of page structure
• Multiple paragraphs of text additions or re-arrangements
• Addition of complex graphics, tables, quotes or other structures
• Large numbers of links and other navigation
• Other major changes that take over a day and will require review before implementing

1.2 Approach For Large Scale Changes

The “Branching and Merging” approach is based on tried-and-true techniques used in modern programming.

It makes use of existing parent / child relationships in SWEHBVD. It allows for: 

• leaving a page in production until its replacement is completed and ready for implementation, 
• reviewers may check on changes and comment prior to implementation, 
• minimizing work during rollout of the new content, 
• preserving all change histories in case rollback is needed. 

 2. From The Reviewer's Perspective

Reviewers see only part of the process. A simplified view of the process includes: 

1. Branch – Editor builds a Review page in the hierarchy under the Real page. The Review page will contain a complete copy of the Real page including updates to the page.
2. Review - Editor sends to reviewers a URL to the Review page 
   1. Reviewers use the URL to view the Review page
   2. Reviewers comment on the changes
   3. Editor and reviewers cycle through comments as necessary during the review cycle making additional changes. Changes being made in the Review page until everyone is satisfied with the changes. 
3. Merge - Editor copies changes from the Review page back into the Real page. 
   1. Verifies that Real page is functioning properly.
   2. Deletes (or move to safe area) Child page when verification is complete

3. From the Editor's Perspective

3.1 Page Titles And Keys

Most pages (SWEs, Topics, etc.) in SWEHBVD have some child pages. Links to these pages can be seen by expanding the “Instructions for Editors” below the References in the Resources tab. They include:

• Key Related SWEs
• Key Related SM
• Key Related Activities

All child pages have a Key (prefix) that correspond to that of the parent

• SWE keys are formatted using 7 characters: “SWE-999”
• SM keys are formatted using 4 characters : “X.YY”
• Keys ensure that the “refstable” macro will work properly
• This also keeps the pages tied together in the hierarchy of pages with this common key

Creating the branch is done from the parent page to maintain the integrity of this hierarchy. 

3.2 Example Of Pages In The Page Tree

The portion of the page tree for this example of a SWE would look like:

• SWE-876 – Programming Code
  • SWE-876 – Related SWEs
  • SWE-876 – Related SM
  • SWE-876 – Related Activities
  • SWE-876 – Review of Programming Code

The page with “Review of” in the title is the branch

• The entire body of the parent page is copied into the branch at the start of the re-construction
• The Parent page remains available to users during re-construction
• All changes are made in the branch or “Review of” page

3.3 Creating The "Review of" Page

Detailed instructions for this page 

1. View the parent page in a browser window or tab.
2. Hover over the large plus sign icon (under the Search area on the right) to view options
   1. Create Content
   2. Create a Space
3. Click on the “Create Content” option to begin creating a new page as a child of the parent page
4. Use the “Blank Page” option and click “Create” to open the new page
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
5. In the newly created page, enter a title, Use the same title as the Real page with the words "Review of" added between the key and the text of the title:
   1. in our example, “SWE-876 – Review of Programming Code”
6. Save the page and verify that it is empty
7. In another tab, open a copy of the parent page and Edit it
8. Use the “Select All” in the parent page (Ctrl-A) and start a copy (Ctrl-C)
9. In the “Review of” page, open it in the editor and paste in the content from the parent page (Ctrl-P) into the Review page.
10. Save both pages and verify that everything copied over properly and both pages have identical content that displays properly. 

You should now have a functional copy of the parent in the “Review of ” page.