# 6. Release Candidate (RC) Development¶

## 6.1. Overview¶

VisIt normally has two active branches for doing development. The first is develop and the second is the current release candidate. Work performed on the develop branch will go into the next major release, such as 3.1. Work performed on the current release candidate will go into the next minor release, such as 3.0.2. When doing work on the release candidate the normal sequence of operations is as follows:

• A branch is created off the current release candidate.
• Changes are made on the branch.
• A pull request is generated to merge the changes to the current release candidate.
• The changes are then merged into the release candidate.
• A branch is created off of develop.
• The changes from the branch off the release candidate are applied to the branch.
• A pull request is generated to merge the changes to develop.
• The changes are then merged into develop.

In some instances the changes made to the release candidate are not applied to develop, in many instances the exact same changes can be applied to both the release candidate and develop, and in some instannces the changes applied to the two branches are slightly or significantly different.

Changes to files impacting communication protocols or public APIs are not permitted on a release candidate (RC) branch unless explicitly agreed to by the team. Communication protocol files are any XML files and their associated auto-generated header files for state objects (any class derived from AttributeSubject) passed between VisIt components (e.g. viewer and engine_par) such as all XML and header files in src/common/state and src/avt/DBAtts/MetaData. Files impacting public APIs include any XML or header files used by database, plot or operator plugins as well as src/avt/Database/Database and src/avt/Database/Formats.

The rest of the section will go through the steps of the most common case of making the exact same changes to both branches using an example of updating the 3.0.2 release notes on the 3.0RC and develop.

## 6.2. Creating the RC branch¶

First you checkout the 3.0RC and then create your branch.

git checkout 3.0RC
git checkout -b task/brugger1/2019_09_05_update_release_notes


## 6.3. Making the changes¶

At this point you would modify your branch as you normally do, modifying, adding or deleting files, and then commiting the changes to the branch.

## 6.4. Creating the pull request on the release candidate¶

Once you have committed all your changes to the branch you are ready to create the pull request. You will start out by pushing your changes to GitHub as normal.

git push --set-upstream origin task/brugger1/2019_09_05_update_release_notes


Now you go over to GitHub and create your pull request. When creating your pull request, make sure that you are merging it into the release candidate.

Now you go through the normal pull request process. Once you have merged your changes into the release candidate you can delete the branch at GitHub and locally.

git remote prune origin
git remote update
git checkout 3.0RC
git pull
git branch -D task/brugger1/2019_09_05_update_release_notes


## 6.5. Apply the same changes to develop¶

Typically, the same changes applied to the release candidate also need to be applied to develop. This is not always the case however. Some changes are made only for the release candidate and should never get applied to develop. Our practice is to require the last comment in every pull request to the release candidate to include a remark indicating either that the PR was not applied to develop or that the PR was applied to develop along with the commit in which it was applied to develop. Typically, the PR for the release candidate has already been closed when this comment needs to be added. This is fine. Developers can still add this comment to a PR when it is in a closed state.

You will apply your changes from the 3.0RC to develop by creating a patch of your changes to the 3.0RC and applying them to a branch created off of develop. The easiest way to create the patch is immediately after you have merged your changes into the release candidate before anyone else makes any changes. In this case you can get the last set of changes from the head. If someone else has made changes in the mean time you will need to use the SHA of your merge to the release candidate. When we create the branch to make the changes on develop, you can use the same name as you used on the release candidate branch and add _develop. Normally, you can omit the first two steps below since you presumably just did that a moment ago.

git checkout 3.0RC
git pull
rm -f patch.txt
git format-patch -1 HEAD --stdout > patch.txt
git checkout develop
git pull
git checkout -b task/brugger1/2019_09_05_update_release_notes_develop
git am -3 < patch.txt


In the case where you need to use the SHA to create the patch, you can get it from the code tab at GitHub for the release candidate branch.

The command to create the patch would then look like:

git format-patch -1 69b0561 --stdout > patch.txt


Sometimes conflicts occur when applying the patch. This may happen with frequently updated files such as the release notes. If that happens you will get a message similar to the one below indicating which files had conflicts.

Applying: Updated the 3.0.2 release notes. (#3867)
Using index info to reconstruct a base tree...
M       src/resources/help/en_US/relnotes3.0.2.html
Falling back to patching base and 3-way merge...
Auto-merging src/resources/help/en_US/relnotes3.0.2.html
CONFLICT (content): Merge conflict in src/resources/help/en_US/relnotes3.0.2.html
error: Failed to merge in the changes.
Patch failed at 0001 Updated the 3.0.2 release notes. (#3867)
The copy of the patch that failed is found in: .git/rebase-apply/patch
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".


In our case it was the release notes. The file will be modified with the conflicts highlighted in the normal >>>>>>>>, =========, and <<<<<<<< notation. You can go in and edit the files and then do a git add for each file that was in conflict. After that point you can do a git am --continue.

vi src/resources/help/en_US/relnotes3.0.2.html
git add src/resources/help/en_US/relnotes3.0.2.html
git am --continue


Now you changes will have been commited to the branch with the appropriate commit message. You are now ready to push the change to GitHub and create a new pull request.

## 6.6. Creating the pull request for develop¶

You first push your changes to GitHub as normal.

git push --set-upstream origin task/brugger1/2019_09_05_update_release_notes_develop


Now you go over to GitHub and create your pull request. When creating your pull request, make sure that you are merging it into develop.

In the description you can simply say that you are merging from the release candidate into develop rather than providing all the normal pull request information. If you are resolving an issue, you will want to mention that, since the automatic closing of issues only happens when you merge into develop.

Once you have merged your changes into develop you can delete the branch at GitHub and locally.

git remote prune origin
git remote update
git checkout 3.0RC
git pull
git branch -D task/brugger1/2019_09_05_update_release_notes_develop


That’s it. You have now made the exact same change to both the 3.0RC and develop.

Once the PR to develop is merged, go back to the PR for the release candidate (it will probably be in a closed state but that is fine) and add a comment there indicating that the PR was also applied to develop and include the commit, from above, where it happened.

Lastly, sometimes changes worth including in the release candidate nonetheless get done first on develop. When this happens, we need to backport the changes to the release candidate. A procedure similar to what is described above can be followed except the roles of develop and release candidate branches are reversed. In addition, once the changes are backported to the release candidate, go back to the PR for develop (it will probably be in a closed state but that is fine) and add a comment there indicating that the changes were also backported to the release candidate and include the commit.

## 6.7. Re-review of PRs for merging already reviewed and merged work to a different branch¶

As described above, there are typically two active branches where work may be going on in VisIt; the currently active release candidate branch and develop. The common case is for developers to do work on the release candidate and then apply the same work to develop using the format-patch or cherry-pick workflows. As noted in the section just above, sometimes the reverse happens and the work is originally done on develop and then backported to the release candidate.

In either case, the question arises, is a second review of a pull-request of the same work to another branch required? The short answer is no. Work that was done and originally reviewed as a pull request to the release candidate does not require a second review in the pull request and merge to develop. This is true even when backporting from develop to the release candidate.

However, there are cases where the release candidate and develop branches have diverged significantly enough that re-review of the work might be needed. A good indicator of this need is if conflicts are encountered when using the format-patch or cherry-pick workflows to merge the changes to a different branch. When that happens, the developer should give some thought as to whether the changes necessary to resolve the conflicts are significant enough that re-review may be required. This is entirely up to the developer doing the work though other developers who may be watching are also free to make a request to re-review the pull request to the different branch.