Topic branch workflow using checkin test script

UNDER DEVELOPMENT

Overview

Many different workflows can be used to create and manage branches and submit Trilinos Pull Requests. One such workflow is described here. The only firm requirement is that a topic branch (of any name) gets pushed to your GitHub fork repo and a Pull Request (PR) is created against the 'develop' branch on the main github.com/trilnos/Trilinos git repo. However, the adoption a good workflow can make things run more smoothly and avoid common mistakes.

The process summarized below describes how one can use the checkin-test-sems.sh script (and/or any other checkin-test.py wrapper scripts) as part of the Trilinos topic-branch workflow. Using the checkin-test-sems.sh script can help to avoid initial auto PR testing failures that overburden the auto PR system and slow down the final merge of everyone's PRs. Also, using the checkin-test-sems.sh script locally will provide faster feedback and make it easy to reproduce failures if they should occur locally. And the checkin-test.py script can be used to drive extra builds that the auto PR tester does not run like full complex builds (using ./checkin-test-sems.sh and various ATDM builds on different platforms like with using checkin-test-atdm.sh). However, this workflow can be run without the usage of the checkin-test.py script as well and can use any type of local testing desired.

Setup and Topic-branch workflow

Initial setup

1) Create a GitHub fork of the main Trilinos repository (one time only)

• Create Trilinos fork in your GitHub account <github-username>:
  • Click on "Fork" on upper right on the page github.com/trilinos/Trilinos then select your <github-username> as the destination
• Make the default branch develop in your fork (or delete develop and create a dummy dont-use-this-branch, see delete-all-branches-in-new-fork below)
• Delete all other existing Trilinos branches in your fork (e.g. 'master', 'trilinos-release-xxx', etc.)

2) Set up local Trilinos git repo (one time per local repo)

• Set up minimal Git settings for your account and Install Git helper scripts on this machine (one time per user home directory)
• Load your public SSH key to your GitHub account (see Connecting to GitHub with SSH) (one time per user home directory)
• $ cd <some-base-dir>/
• $ git clone -o upstream -b develop [email protected]:trilinos/Trilinos.git
• $ cd Trilinos/
• [(develop)]$ git remote add my-fork [email protected]:<github-username>/Trilinos.git
• [(develop)]$ git fetch my-fork (Make sure remote set up correctly)
• NOTES:
  • When using multiple git repos and more sophisticated workflows, best not to call any git repo remotes origin. Be explicit with remote names like upstream and my-fork (or whatever you want to call these remote repos so that this is clear to you what they represent).
  • If your local repo is already cloned from the main Trilinos git repo, the repo can be set up using:
    • $ cd Trilinos/
    • $ git remote rename origin upstream

3) Set up to use checkin-test-sems.sh [optional] (one time per local repo)

• $ cd <some-base-dir>/
• $ mkdir CHECKIN/
• $ cd CHECKIN/
• $ ln -s ../Trilinos/cmake/std/sems/checkin-test-sems.sh .
• $ ./checkin-test-sems.sh (Generate the local-checkin-test-defaults.py file)
• Edit the local-checkin-test-defaults.py file for your machine:
  • Set -j<N> for your machine
  • Only increase --ctest-timeout=<seconds> if you have timeouts on your machine
• NOTE: Usage of a checkin-test.py script is optional.

Topic-branch workflow

1) Create a new topic branch (one time per each new topic branch)

[       (<brnch>)]$ git fetch upstream
[       (<brnch>)]$ git checkout -b <topic-branch> upstream/develop
[(<topic-branch>)]$ git push -u my-fork <topic-branch>

• NOTE: A good name for <topic-branch> is <gitub-issue-id>-<some-descriptive-name> like 1234-tpetra-fix-global-reduction. See github-issue-before-topic-branch.

2) Add commits to local topic branch (one or more times per topic branch)

• $ git checkout <topic-branch>
• Edit files, build and run tests locally, create local commits, iterate
• NOTES:
  • Please create commit messages that reference the associated GitHub ID (e.g. #1234, see github-issue-before-topic-branch)
  • Please create logically separate commits (see "SEPARATE CHANGES" in gitworkflows(7) man page)
  • The checkin-test-sems.sh script can be used for local testing as well, see checkin-test-local.
  • You can push the updated topic branch to your GitHub fork at any time using git push in order to back it up or share it with others. Just remember that if a PR has already been created for this topic branch (see Submit Pull Request and early-pr-creation) then one should add the AT: WIP label to avoid excessive or unwanted testing of the branch until the branch is ready to be tested.

3) Update local topic branch from 'develop' [optional] (one or more times per topic branch)

[       (<brnch>)]$ git checkout <topic-branch>
[(<topic-branch>)]$ git fetch upstream
[(<topic-branch>)]$ git merge upstream/develop     # Using a merge, or
[(<topic-branch>)]$ git rebase upstream/develop    # Using a rebase (See 'git rerere')

• NOTES
  • Don't uses git rebase if you are sharing this topic branch with other developers (see shared-topic-branches)!
  • Must enable git rerere for rebases to go smoothly (see Set up minimal Git settings for your account).

4) Clean-up and rebase of local topic branch [optional] (one time per topic branch)

[       (<brnch>)]$ git checkout <topic-branch>
[(<topic-branch>)]$ git pull
[(<topic-branch>)]$ git fetch upstream
[(<topic-branch>)]$ git rebase -i upstream/develop

• NOTES:
  • Final cleanup with git rebase -i is optional but it creates a cleaner git graph and cleaner commits.
  • See documentation on git rebase -i)

5) Test and push cleaned-up topic branch (one time per topic branch)

$ cd <some-base-dir>/CHECKIN/
$ ./checkin-test-sems.sh -a off -p <pkg0>,<pkg1>,... -A -P -F  

• NOTES:
  • Must be on <topic-branch> in the local Trilinos git repo before running this and that topic branch must be in a state ready to push (see Clean-up and rebase of local topic branch).
  • If not wanting to test downstream (forward) packages, add option -n (--no-enable-fwd-packages).
  • If wanting to test all packages, change -a off -p <pkg0>,<pkg1>,... to -a on.
  • Usage of ./checkin-test-sems.sh (or even any local testing) is optional. Instead, one can just run git push -f.
  • If a rebase was not used, the checkin-test.py forced-push argument -F can be left out or a basic git push can be performed if not using the checkin-test script.

6) Submit a Pull Request (one time per topic branch)

• Submit a pull request for the branch https://github.com/<github-username>/Trilinos/branches/<topic-branch> against the develop branch in https://github.com/trilinos/Trilinos:
  • Just after you push an updated <topic-branch>, your branch will appear at the top of the page https://github.com/trilinos/Trilinos. Just click on the "Compare & Pull Request" button to the right of the branch name.
  • Change the target branch to develop (not the default master branch)
  • Add @trilinos/<package> and other @<github-user> mentions to the comment field for the teams and people who should be aware of this PR.
  • Set the reviewers for the PR
  • Add labels for the packages impacted and other relevant labels, milestones, etc.
• NOTE: If the PR is to be created before the branch is ready to be tested, then set the AT: WIP label.

7) Watch for auto PR testing results

• Watch for emails about the auto PR tests starting and completing.
• When the "PASSED" or "FAILED" auto PR test email comes in, look at results in Pull Request CDash Group details about what got tested and the details of any failures.
• Auto PR builds can be reproduced in local machines as described at Reproducing PR Errors.
• NOTES:
  • The PR must be reviewed by a Trilinos developer before it will be allowed to be merged.
  • If the PR branch is not getting tested by the auto PR tester, make sure that the label AT: WIP is removed and make sure that a Trilinos developer has approved the PR (or the PR was created by a Trilinos developer). See Pull Request Testing for details.

8) Merge the topic branch in the PR

• Use the "Merge" or the "Squash" option if there is more than one commit on the topic branch. (It is okay to use the "rebase and merge" option if there is only one commit on the topic branch.)
• WARNING: If it has been a long time since the last auto PR builds were done, then merging could break the develop branch. In this case, add the label AT: Retest and let another round of auto PR testing run and complete before merging. (This is needed to avoid violations of the additive test assumption of branches as occurred, for example, in #2264.)

9) Delete topic branch after final merge [optional]

$ cd <some-base-dir>/Trilinos/
$ git push --delete my-fork <topic-branch>   # Delete the branch in your GitHub fork
$ git branch -d <topic-branch>               # Delete the branch in your local git reppo

Summary, Notes and Comments

[repo-setup] Note that the setup of the local git repo described here is slightly different from what is described in Pull Request Workflow. The setup above, arguably, avoids some common confusion and involves less boiler plate commands than are required by that process. Otherwise, the workflow described here and the one described in that description are interchangeable. All that matters in the end is that a topic branch (of any name) gets pushed to your GitHub fork repo and a Pull Request (PR) is created against the 'develop' branch on the main github.com/trilnos/Trilinos git repo.

[delete-all-branches-in-new-fork] When setting your fork of Trilinos, deleting all of existing branches that come in from the main Trilinos git repo will avoid people cloning your fork repo and then accessing stale branches and will avoid you having to update existing branches in that fork for no good reason. Also note that one can delete the 'develop' branch in the fork repo as well by creating a dummy branch like dont-use-this-branch and making that the default branch for the fork. (You can see an example of this in the GitHub fork https://github.com/bartlettroscoe/Trilinos).

[github-issue-before-topic-branch] One should not start work on a topic branch until a GitHub issue has been created describing the need for this topic branch. Note that more than one topic branch can be associated with a single GitHub Issue. And this GitHub Issue ID (e.g. #1234) should be embedded in the topic-branch name and in all of the git commit messages on that topic branch.

[checkin-test-local] To test your local topic branch at any time (no matter the state of the local git repo) use:

$ cd <some-base-dir>/CHECKIN/
$ ./checkin-test-sems.sh -a off -p <pkg0>,<pkg1>,... -L

Also, other custom checkin-test.py wrapper scripts can be used for local testing as well such as the checkin-test-atdm.sh script for helping to test with ATDM builds of Trilinos.

[early-pr-creation] Note that you can create the PR for your topic branches at any time after the initial push of your topic branch. You don't need complete your topic branch before you do this. But if you create your PR early, you might want to set the label AT: WIP to avoid overburdening the auto PR testing system. Then, once you are ready for a fuller set of tests, remove the AT: WIP label and let the auto PR system run these builds.

Note that currently one must explicitly list the packages to be tested using -a off -p <pkg0>,<pkg1>,.... In the future, an argument --compare-to=github:develop will be supported that will automatically determine what needs to be tested based on changes in your local topic branch compared to what is in the upstream/develop branch.

[shared-topic-branches] Note that the above description really describes a uniquely owned topic branch that only one developer creates and pushes to. But extending this to a shared topic branch with many developers is also possible as described in the section add topic branches in the document Design Patterns for Git Workflows. The only difference from what is described there is that one can use a checkin-test.py script to locally test changes and to test and push the updated topic branch. But when sharing topic branches, one must be very careful not to rebase the topic branch until the final cleanup, unless everyone knows what they are doing with these rebases and work very carefully. (Only developers with advanced git knowledge and skills should attempt rebasing except for at the very end for the final cleanup and push.)