6. Release Candidate (RC) Development¶
VisIt supports three types of releases, major, minor and patch.
VisIt’s version number is of the form
Patch releases are the most common type of release and typically occur three to four times a year.
Minor releases are the next most common type of release and may occur once or twice a year.
Major releases happen infrequently, with perhaps several years passing between major releases.
For example, the release sequence goes something like patch (2.12.0), patch (2.12.1), minor (2.13.0), patch (2.13.1), patch (2.13.2), patch (2.13.3), minor (2.14.0), patch (2.14.1), minor (2.15.0), patch (2.15.1), patch (2.15.2), major (3.0).
The VisIt project normally maintains just two stable branches of development.
These are the current release candidate (RC) branch named something like
3.3RC and the main development branch named
All patch releases of VisIt are made from the current RC branch.
3.3.3 are all patch releases made from the
When the next minor release is to be made, say
3.4.0, a new RC branch, named
3.4RC, is created from the current
3.4RC branch becomes the current RC branch and all work on the
3.3RC branch ceases.
3.3RC branch will remain forever available.
Most work on VisIt is performed first on the current RC branch and then the same changes are applied also to the
In this way,
develop will have all changes that were made on the current and all previous RC branches.
Sometimes, short term fixes are performed on the RC branch only because they are never intended to become perminent.
Likewise, sometimes long term enhancements are performed only on the
develop branch because they introduce significant changes in interfaces and/or dependencies.
Unless you have been instructed otherwise, plan to do your work first on a branch from the current RC branch in one pull request and then apply those same changes on a branch from
develop in a second pull request.
Use VisIt’s GitHub milestones page or or reach out to the VisIt team on our GitHub discussions page if you need help identifying the current RC branch or deciding upon which branch you should start your work.
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
engine_par) such as all XML and header files in
src/avt/DBAtts/MetaData. Files impacting public APIs include
any XML or header files used by database, plot or operator plugins as well as
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
This is not always the case however.
Some changes are made only for the release candidate and should never get applied to
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
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
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
<<<<<<<< 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
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
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
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
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
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.