Create 12.12 release
Created by: bmpersc
Following checklist below and updating as needed:
''' rev 2016/07
Creating a New Trilinos (Release) Branch with GIT
Note: these instructions have been updated to use gitdist from the copy of tribits inside of the Trilinos repo. All of the commands assume that you will need the full path to gitdist, however, if you have setup your PATH or an alias that may be unnecessary. Also, as of the time of this writing, there is a known issue with gitdist that it ignores optika. It is assumed this is a bug and the commands for Optika have been omitted. If this issue persists and Optika is still released you will need to cd into packages/optika and run most of these commands by hand there, replacing gitdist with git.
A GIT branch can be used to maintain a version of the code that is different than the primary development branch. This process describes how to create a Trilinos release branch, but the steps can easily be generalized to apply to other types of branches. There are eight steps in creating a Trilinos release branch:
Clone Trilinos
You need to be in a clean state in order to branch Trilinos. It is best if you start from a fresh clone, but any repository that is up-to-date and in a clean state (no modified/untracked/etc files) can be used. This does mean that you can not make changes and have them apply to the branch unless you have commited them first. You will also need to clone each of the external repos that we release. These repos will need to be cloned into the packages directory.
The list of external projects as of 1/12/2016 is: CTrilinos ForTrilinos mesquite moocho optika Sundance
To clone a copy of Trilinos type:
Command: git clone git@github.com:trilinos/Trilinos cd Trilinos ./clone_extra_repos.py --not-extra-repos=preCopyrightTrilinos
Despite the default for clone_extra_repos.py being "Nightly" it apparently always clones preCopyright unless told not to.
Tag the working copy
The existing branch is now tagged to mark the point where the new branch will diverge. This will need to be done for every external repository as well as the Trilinos repository. To do this, from anywhere in your clone type
Command: cmake/tribits/python_utils/gitdist tag -a -m ""
For a release branch, tag name should be root-of-trilinos-release-XYZ-branch, where XYZ is the release number with the component numbers separated by hyphens instead of periods. For example for release 3.1.13, XYZ should be 3-1-13.
Create a branch
To create a branch, from anywhere in your clone type
Command: cmake/tribits/python_utils/gitdist branch
For the Trilinos release version XYZ mentioned above, the branch name should be trilinos-release-XYZ-branch.
Update to convert the working copy to the new branch
The act of creating a new branch does not change the existing working copy to a that branch. To make this switch type
Command: cmake/tribits/python_utils/gitdist checkout
To verify that the preceding command was successful, type
Command: cmake/tribits/python_utils/gitdist branch
The branch you are on will have a '*' infront of it.
Updates to make to the code when branching
When creating a new Trilinos release branch, the Trilinos version number needs to be updated in the Trilinos/Version.cmake file. The values for Trilinos_MAJOR_VERSION, Trilinos_MAJOR_MINOR_VERSION, Trilinos_VERSION_STRING, and Trilinos_VERSION need to be updated. Also the Trilinos_REPOSITORY_BRANCH will need to be set to the correct branch name and Trilinos_TESTING_TRACK will need to be set to the correct cdash track. As well as ${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE will need to be set to OFF. This file also needs to be updated on the master branch, However only the version numbers should be changed to reflect the new development version.
Finally, git commit the changes. In the commit message, note that branch name is listed.
Tag the new branch
It is a good idea to tag the branch at this point so that the initial state of the branch is easily retrievable. To perform this step, type
Command: cmake/tribits/python_utils/gitdist tag -a -m ""
For the Trilinos release version XYZ mentioned above, the initial tag name should be initial-trilinos-release-XYZ-branch.
Make the branch and tags public
At this point none of these changes, tags or the branch will be publicly available we need to push them to the public repository, which should be origin. There is a special way that you have to push branches to the public repository. To push the branch type
Command: cmake/tribits/python_utils/gitdist push -u origin :
This will push the branch named and the new commits on it from your clone to origin with the name . Note that you can rename the branch by giving a different name for , but recommend not doing this unless you need to fix the name of the branch for some reason.
Tags are easier to push, you can push them one at a time like the branch, but it is easier to push all of them at once. To push the tags type
Command: cmake/tribits/python_utils/gitdist push --tags
Test the new branch
It is a good idea to test the new branch to help make sure that the above process has been completed properly. As a part of the general release process, many tests need to be run. This step simply refers to running a few simple sanity checks (for example, build a few Trilinos packages and run ctest for those packages) to work out any obvious problems before the branch is subjected to the more complete test suite.
Reference on related git commands:
When you clone Trilinos you get a copy of every branch and tag that is on the public repository. However, you do not have a local copy of the branch (unless you used eg to clone) until you set it up. To checkout a different branch of Trilinos, from the repository you just cloned type
Command: git checkout --track origin/
This will create a local branch for the given branch and check it out for you. In addition any changes made to this branch will be pushed back to the correct branch on origin when you push. This is what is called a tracking branch. Once you have created a local tracking copy of a branch you won't have to do it again in the same clone. Instead if you want to go to a different branch, back to master for instance, and want to checkout the branch again you only need to type
command: git checkout
Tags, like branches, are all copied to your local repository when you clone. Checking out a tag is similar to checking out a branch, but since tags only point to a specific commit you do not need to create a local copy of the tag, you only need to type
command: git checkout
'''