When to Change the Base Branch on a User Story

Overview

When your pipeline has work in-flight that has not yet made it to production, and you continue to create and deploy new user stories that stack additional work on top of those earlier stories, Git can struggle to merge metadata. This is specifically a problem with page layouts, but can affect any metadata in your pipeline.

Example

User-added image
  • User story 1 contains an additional field (A) on the page layout.
  • User story 2 contains field (A) plus an additional field (B) on the page layout.

After deploying user story 2 to SIT, you expect the resulting file to have the following layout:
 
Expected resultActual result

 

<Layout>
-Field A
-Field B
</Layout>


<Layout>
-Field A
-Field B
-Field A
</Layout>

Resolution
There are three strategies to deal with this scenario:
  1. Release work to production when it’s ready, not when the release is scheduled.
Pushing code to the master branch faster will put the changes in new base branches, thereby stacking commits appropriately. Remember that Copado was built with Agile practices in mind.
  1. Set the base branch of user story 2 to be the feature branch of user story 1.
In the diagram above, user story 1 and user story 2 are committing the same work, but in different commits. This results in a duplicate when you merge. If you set the base branch of user story 2 to be the feature branch of user story 1, you have the incremental history now in user story 2. When user stories 1 and 2 collide in your pipeline, git can merge the contents of user stories 1 and 2 without duplicates.
 
Initial Creation of User Story 2
  1. Create the user story.
  2. Commit the components:
    1. On the commit screen, select the Advanced button. If you’re not able to see it, you need to add the Edit User Story Commit Base Branch custom permission to your profile. 
    2. Select user story 1 as the base branch (user story 1 in the diagram above). For more information, refer to the How to Commit Changes article.
    3. Commit your components as normal.
  3. Deploy the user story up the pipeline.
ⓘ Please be aware that if you deploy user story 2 past user story 1, you are deploying the work of both stories.
  1. Set an environment branch as the base branch of your user story.
Between solutions 2 and 3, 2 is preferred. If you can’t find the original story, however, or if there are multiple stories, you can set an environment branch to be the base branch for your story.
 
Initial Creation of User Story 2
  1. Create the user story.
  2. Commit the components:
    1. On the commit screen, select the Advanced button.
    2. Select destination as the base branch (SIT in the diagram above).
    3. Commit your components as normal.
  3. Deploy user story up pipeline until it reaches the base branch environment.
ⓘ Do not deploy the user story past the base branch environment. You will wreck your pipeline if done.
  1. You must recommit and recreate the user story at this destination with the production branch (default) as your base.
    1. Open the user story and click on the Commit Changes button.
    2. Change the operation from Commit Files to Recommit Files.
    3. Flag the Recreate feature branch box.
    4. On the commit screen, select the Advanced button and select master as the base branch.
    5. User story components should already be selected. Click on the Commit Changes button.
    6. The user story is now ready to be deployed through the remaining pipeline.
Note: You may have to do this repeatedly for environments up your pipeline.



How did we do?