Git Notes Testing Pull Requests

Checking Out the Pull Request

As a project member you may need to accept or reject a pull request either from another member or an outside collaborator. Here we will show how to test the changes before merging them into the central repo. The basic process is discussed here. Below we will follow an example for a set of changes to the FDS User Guide, which is fairly easy to test.

Let's follow the procedure for accepting pull request #2809. The first step is to fetch the commit to your local repo. The syntax is

$ git fetch repo pull/ID/head:BRANCHNAME

Here the ID is the number of the pull request (in this case 2809) and the BRANCHNAME is whatever you want to call it in your local repo. Here we will call it test_2809.

$ git fetch firemodels pull/2809/head:test_2809
remote: Counting objects: 36, done.
remote: Compressing objects: 100% (36/36), done.
remote: Total 36 (delta 23), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (36/36), done.
From git://github.com/firemodels/fds-smv
 * [new branch]      refs/pull/2809/head -> test_2809

Note that firemodels is the name of the central repository set up for remote tracking in my forked repository. If I were working directly within a clone of the central repository, I would refer the repo as origin.

Now do a git branch to see what branches you have locally.

$ git branch
* development
  test_2809

You will see that you have fetched the branch test_2809, but you are still on branch development.

Now checkout the new test branch.

$ git checkout test_2809
... (what you see here depends on what you have modified in your local repo; you may want to [stash] your changes before starting this process)

OK, now run your test to determine if the pull request does what it is supposed to do. In this case, we go to Manuals/FDS_User_Guide/ and run $ ./make_guide.sh, and we should see FDS User Guide built successfully! in addition to the correct additions having been made to the guide.

If successful, then you can simply accept the pull request on GitHub. If there is a problem, you can either write the author to make changes and Close and Comment the conversation (the author will need to make another pull request) or you can make the changes yourself in your local test repo and push those to YOUR origin and submit a pull request to the central repo from there. We discuss this option next.

Often it is the case that the pull request is 99 % of the way there, but may need a few minor edits in order meet all the Developer Commit Guidelines. In this case, it is usually easier for the developer to make the local changes themselves and then push to their own forked repo. If you are the developer and if you have followed the instructions to this point you will not have a copy of the new test branch in your GitHub repo. Once you have made the changes in the test branch (add and commit them) you can push this new branch to GitHub via

$ git push -u origin test_2809
Counting objects: 13, done.
Delta compression using up to 12 threads.
Compressing objects: 100% (9/9), done.
Writing objects: 100% (9/9), 1.04 KiB, done.
Total 9 (delta 7), reused 0 (delta 0)
To [email protected]:rmcdermo/fds-smv.git
 * [new branch]      test_2809 -> test_2809
Branch test_2809 set up to track remote branch test_2809 from origin by rebasing.

You can now submit this branch as a pull request to the central repo. Then accept that request.

Once this is done you will want to fetch and merge the changes into your local development branch (see Git Notes: Getting Started).

$ git checkout development
$ git remote update
Fetching origin
Fetching firemodels
remote: Counting objects: 1, done.
remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (1/1), done.
From git://github.com/firemodels/fds-smv
   59ab030..0a17223  development -> firemodels/development
$ git merge firemodels/development
Updating 59ab030..0a17223
Fast-forward
 Manuals/FDS_User_Guide/FDS_User_Guide.tex |   21 +++++++++++++--------
 1 files changed, 13 insertions(+), 8 deletions(-)
$ git push origin development
Counting objects: 49, done.
Delta compression using up to 12 threads.
Compressing objects: 100% (37/37), done.
Writing objects: 100% (37/37), 4.37 KiB, done.
Total 37 (delta 28), reused 0 (delta 0)
To [email protected]:rmcdermo/fds-smv.git
   59ab030..0a17223  development -> development

And finally you need to delete the test branch from your local repo.

$ git branch -d test_2809
Deleted branch test_2809 (was 31be744).

Do a git branch to see that the test branch is gone.

$ git branch
* development

Note that usually GitHub will tell you that you may delete the test branch on your forked repo on GitHub. Go ahead and click the delete button (it gives you a restore, just in case). If you forget to do this, you will eventually want to get rid of your remote test branch in your forked repo. Then you will have to do either

$ git push origin :test_2809

or

$ git push origin --delete test_2809

Running Firebot

I have only successfully run a complete Firebot session from the machine blaze.el.nist.gov. In the next section, we will discuss a truncated run script for only testing FDS cases, which might be sufficient for testing the pull request. In the mean time, I assume you are on blaze and within your FDS-SMV repo.

CD into Utilities/Firebot and type

$ nohup ./run_firebot.sh -b branchname &
[1] 12669
[rmcdermo@blaze Firebot]$ nohup: appending output to `nohup.out'

The terminal will look like it's working and won't give you a command prompt. Go ahead and hit Enter to get back to a command prompt. Then type the following and go to lunch.

$ tail -f nohup.out
Preliminaries:
     running in: /home/rmcdermo/GitHub/fds-smv_rmcdermo/Utilities/Firebot
   FDS-SMV repo: /home/rmcdermo/GitHub/fds-smv_rmcdermo

Cleaning
   run directory
Building
   FDS
      inspection

Now whenever Firebot completes various stages you will see the results in your terminal window.

Running FDS_Cases.sh

The list of cases in the FDS verification suite is in Verification/FDS_Cases.sh. There are a few reasons why you may want to utilize this list for testing your pull request. First, if you do your development on a machine other than blaze (I use burn or my laptop most of the time), it is a hassle to migrate your branch over to blaze for a full Firebot session. Next, if your changes would pass a build, FDS run, and Matlab plot, then it should be reasonable to merge and let the full Firebot run overnight. Last, it may be that you only want to run a subset of the cases, in which case you could comment out other cases in FDS_Case.sh, or modify scripts/Run_FDS_Cases.sh (which we will talk about next) to run your select cases.

The downside of using Run_FDS_Cases.sh is that there are few things you must do manually, but these are really not too onerous.

Step 1: Do a clean compile of both debug and MPI release versions of the code. From the top level of the repo do

$ cd FDS_Compilation/intel_linux_64_db
$ rm *.o *.mod
$ ./make_fds.sh
...

Obviously, if the code does not compile, fix the errors and repeat. But in debug you may also get unused variable warnings. Make sure you fix these too before going on.

Next, compile the MPI release version. Again, from the top level do

$ cd FDS_Compilation/mpi_intel_linux_64ib
$ rm *.o *.mod
$ ./make_fds.sh
...

This will take a little longer to compile. Notice that we are compiling the "infiniband" (ib) version of the code. The network must be the same as the network in /Utilities/Scripts/qfds.sh. Make sure you can run a single case using qfds.sh before trying to launch the verification suite with Run_FDS_Cases.sh!