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

For this example we will use "Review of" in the title as a differentiator. You could also use "NEW " in the title. 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. 

3.4 Develop New Content

 The page "SWE-876 – Review of Programming Code" may now be edited as necessary. 

• Make changes as needed to tabs. 
• Add or delete tabs as necessary keeping the Resources tab at a minimum to preserve the tab structure. 
• Modify the Set-Data macro at the top of the page to point to the tab where the Resources are. 
• Ensure that the Excerpt-Include for the page top message is still in place at the top of the page. 
• Put an Excerpt macro in to provide
  • the wording of the requirement it the page is a SWE or HR page. 
  • the short description of the page to be displayed in the D. Topics page 
• Add or modify content as necessary 
• Add or change links to SWEHB pages as necessary keeping the "Related" pages updated. 
  • Related Activity
  • Related SM
  • Related SWE
• IF new attachments are added or changed they will need to be added to both the old and new pages. 
• When content needs to be reviewed,  send a link to the new page to reviewers so they can access the new page. 

3.5 Release New Content

When the new content is ready to be released, the steps below should be performed: 

• Open both the new page and the old page in "edit" mode. 
• In the old page, use Ctrl-A to select the entire body of the page, "delete" it.
• In the new page, use Ctrl-A to select the entire body of the page, "copy" it using Ctrl-C.
• In the old page, paste the content in using Ctrl-V. 
• Save both pages and do a quality test. 
  • Make sure the content from the new page is properly rendered in the old page. 
  • Check the title to see that it is correct. 
  • Check the tabs to see that they render properly
  • Check the references to see that they appear properly
  • Check the SWEREFN links to see that the go to the right tab in the right page (if they go to the new page, you will have to fix them in the old page). 
  • Check to see that attachments are properly rendered. They may need to be copied into the old page and re added into the old page. 
• Once you are sure the old page is properly functioning and ready for release, do the following: 
  • For a SWE, make sure that the old page still renders properly in the Requirements pages ( B. Institutional Requirements or C. Project Software Requirements). 
  • For Topics, make sure that the old page still renders properly in the D. Topics page. 
  • For a new SWE or Topic, add the page to the appropriate high level page (Requirements or Topics)
  • Build and publish a Blog entry to announce the changes to the page in the Book A. Introduction page. See SWEHBDOC Blogs In SWEHB for details.