Email
Make sure to send an email the day before the branch cut and one the day off in the morning (you can reply-all for the second one) to the mobileapps outlook group with the following format (subject can just be Android Branch Cut (21.01_R1) with the right version of course):
Hi team,
Android branch cut for 21.01_R1 release will be starting at 4pm EST tomorrow, Wednesday February 14. Please make sure to merge your MRs before that.
Thank you,
Later in the day, right before the branch cut is about to begin, reply-all to that email with something like the following:
Hi team,
The Android Branch cut has now began. Please hold off on merging any MRs to master until it’s complete.
I will send a follow-up email to this when it’s done.
Thank you,
And then when the branch cut is done (discussed later in this guide), you can reply-all again:
Hi team,
The Android branch cut is now complete. You can resume merging your MRs into master.
Release branch is created: APP_21.01_R1
Thank you,
First off, you'll need to find the previous app version branches and decide how many you are going back (usually one or two). For this example, we'll assume our new version will be APP_21_03 (for simplicity) and our past two versions will be APP_21_02 and APP_21_01.
Before you follow any of the below steps, make sure to checkout all of the old version branches and master, and make sure to pull all latest changes.
To create an MR you'll need a ticket # in Jira. For that you can just clone this ticket and update the release version in the title to match yours: https://jiramst.federated.fds/browse/ASR-939
This process can be repeated if you want to go back further.
Since we're going back to APP_21_01, we'll create a new branch from the release after that.
So, while being checked out on branch APP_21_02, we create a new branch called dev/backmerge_21.02_Jan_20 (using the right versions/dates).
Then, we are going to merge the APP_21_01 into the newly created branch.
These steps all together all like this (if you're using the terminal):
$ master > git checkout APP_21_02
$ APP_21_02 > git checkout -b dev/backmerge_21.02_Jan_20
$ dev/backmerge_21.02_Jan_20 > git merge APP_21_01
You can also use Android Studio, or the tool of your choice, as long as you are merging the right branches.
If there are conflicts, resolve them using the guide below. If there are none, move to the next step.
Make sure you start on the master branch. From there checkout a new branch called dev/backmerge_21_03_Jan_20 (using the right versions/dates).
Now, the branch that has to be merged into this depends on whether you went back two steps or one. If you went back two steps or more, you'll need to merge your last back-merge branch from that process (i.e. dev/backmerge_21.02_Jan_20 from above) . If this is your only step, you'll need to merge the last release branch (i.e. APP_21_02).
The steps are like this (if you're using the terminal):
$ master > git checkout -b dev/backmerge_21_03_Jan_20
$ master > git merge APP_21_02
(replace APP_21_02 with your last back-merge branch if applicable)
You can also use Android Studio, or the tool of your choice, as long as you are merging the right branches.
If there are conflicts, resolve them using the guide below. If there are none, move to the next step.
While on this branch, build the app and go through it making sure it builds correctly and works properly. When you are ready to proceed, open the dependecies.gradle file at the top of the repository and update the versionNameBase field to the correct new version.
Stage these changes and commit using the new ticket you just created. The commit message can just include the new version name. You can now push these changes up to a remote branch and create an MR to master.
The MR title should include the Jira ticket and the release version. For example: https://mobile-code.devops.fds.com/mobile/android-app/-/merge_requests/12469
If the pipeline fails for some reason, fix the issues and re-commit. When the pipeline for the back-merge branch succeeds, get it approved, and merge it to master, while squashing the commits you made. Once merged, copy the commit sha (the long version) from the commit in the master branch. (Make sure you grab the right one, this is important.)
Now, you can create a DevOps ticket. For that you can clone this ticket, updating the version in the title, and make sure to update the version names and delete the CommitId in the body:
https://jiramst.federated.fds/browse/DEVOPS-14367
Paste that commit id you copied from the MR (again make sure this is the right one) in the DevOps ticket for the Commit ID field, and assign it to the right DevOps person.
At the time of writing this, that person is Maryna Gasanova, but that can change. A good way of checking is looking for the previous branch cut ticket, and who it was assigned to. Usually if you assign it to the wrong person, the DevOps team will re-assign anyway.
From now on, you just need to monitor that DevOps ticket. Keep it open in a tab and refresh it every now and then (this will usually take a few hours to a day, so no need to refresh it very often). When the ticket is resolved, you can go to GitLab and check that a branch with your release name (i.e. APP_21_03) is created as a protected branch. When that branch is created, the branch cut is complete. Now you can go ahead and send that last email informing everyone they can resume merging their MRs to master.
This is by far the hardest and most important part of a branch cut, so make sure to read this thoroughly.
To resolve merge conflicts in any of the steps above, you can use the tool/IDE of your choice, but keep a few thing in mind:
- Try to always resolve the conflicts with both the Primary and Secondary person on a call with screen-share, 4 eyes are better than 2 to catch mistakes
- Be very careful and intentional about which code you keep and what you discard, this is important
- If you're not sure why something is a merge conflict, or which one to pick, follow these steps:
- Open the file in question in both branches that are merging (i.e. if doing a 1-step process, that would be master and the previous release branch)
- Go to the history for each one, and see the commits the changes were made to the file. Compare the two and that should help you figure out which one is the right one to pick, or why the merge conflict is there
- If you still are unsure, don't pick randomly. From the previous step you know the author(s) of the commits in both branches. Ping them on Teams, or ask them to join the call and ask them which one is the right one. It's always better to be sure, so if you have any reservations, asking the person that made the changes is the best bet
- Follow the above steps for each merge conflict
- Double check for any code marked as automatically resolved by git during the merge (it'd show as committed) and make sure everything makes sense. Sometimes git messes up
- When you are done merging, before you commit anything, build the code to make sure you didn't miss anything or mess something up
- If any changes need to be made to make the build pass, you can include those in the merge commit
- Practice makes perfect, the more merges you do, the better you'll become at it. Usually practice will come from dev branches and not branch cut, however 😁
By that I don't mean start the branch cut early, since you send out an email for everyone to adjust around, but you can schedule some time with your other Team member at the start of the day and go through the process steps up to the Finalize portion. Pretty much do the branch merges and resolve the conflicts. This will let you see what merge conflicts you're going to be dealing with when the branch cut time comes, and allows you to do the research, and ping the right people early. This way you won't have to be looking for people during the branch cut, which will delay it (sometimes even by days if certain people are out).
Note that you will have to repeat that process from scratch when the time for branch cut comes, don't re-use your old branches, since people might have merge more MRs into master since you did that in the morning. But you'll most likely have a big head start on the conflicts and you're going to go through those steps much much faster.
Note #2, if you're going back more than 1 step, and you have merge issues on the previous releases, you can always track down some the people that did the previous branch cut and check with them, as they probably had to resolve those themselves.
Sometimes there'll be a lot of new kill switches and you'll be asked to make a common MR for all of them for the prod config. To do that you can just create a new branch off of master for that repo, and format it like this:
https://mobile-code.devops.fds.com/mobile/appconfig-mcom-prod/-/merge_requests/465
Then you can post this MR to the channel that handles the Release and Defects.
Here are some of the links you can use to clone the tickets and check MR format if you don't want to look for them in the guides above: