We use git for revision control. See the following websites for information on using git, e.g. commands, etc.
Main website: http://git-scm.com/
User manual: http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
Short tutorial: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
The manual provides a nice reference, and I suggest reading the first 4 chapters. If you want to understand what is going on “under the hood,” I recommend chapter 7. Many new students are overly cautious when they get a new code. I was no different when I started my masters. I was afraid that I might change something and mess-up the code for everyone else. Fortunately, this kind of experience should be a thing of the past, at least if you use git properly. Therefore, it is important that you appreciate what version control can do, otherwise you will not take full advantage of it. Here are some things to keep in mind:
When you want to try out something new, do not copy the code into a new directory. Just create a new branch using git. Then, if it doesn’t work out, just return to where you branched off.
Commit frequently! When you are working along on a development branch, save your changes by making a commit. You can always revert to a previous version. Once you get the hang of it, you’ll probably commit at least once a day.
Keep a master branch that contains a working up-to-date copy of the code, and at least one working branch. Merge changes into the master branch when you are happy with them.
There is a git GUI installed on Niagara called gitk. Use this in your Jetstream directory to see the different branches, where they merge/diverge, and what other users have done, with the command
>> gitk --all
Periodically, the group will perform a code update procedure where all members will share their latest stable features with the group. See a subsequent section for information on this.
Periodically, a syncing procedure will be conducted to share group member's contributions to Jetstream and to do some benchmark testing. This procedure is described here:
The code gatekeeper will create a staging area with
>> git clone --bare <gatekeeper-username>@oddjob.utias.utoronto.ca:/nfs/carv/d1/people/comp-aero/jetstream.git jetstream_sync_staging_mmyyyy
>> chmod -R g+rwx jetstream_sync_staging_mmyyyy
For each syncing, all or a subset of group members will contribute their changes. You will receive an email listing who will contribute changes. Each member of the list will conduct the following procedure:
Commit any pending changes to your master branch before beginning the merge process. The code you contribute to the group should be stable, have confidence it is working properly and will not break anything for others (this will be tested later), and should be free of extraneous comments, debug statements, etc. Do this with the following command
>> git checkout master
>> git commit -a
Create a branch for merging and check it out
>> git checkout -b merging
Pull from the sync staging area
>> git pull /home/z/zingg/bercikal/jetstream_sync_staging_<mmyyyy>
Resolve conflicts and commit
>> <Edit files to resolve conflicts>
>> git commit -a
Compile with
>> ./make_jetstream
Once it compiles successfully, push back to the staging area
>> git push /home/z/zingg/bercikal/jetstream_sync_staging_<mmyyyy> merging:master
Email the gatekeeper to let them know it was successful.
This procedure will be repeated for each member of the current syncing group.
The gatekeeper will run a suite of tests to make sure that any code changes are back compatible, or if they aren't that there is a good reason for any new results and not the result of a bug.
Once all tests have passed, the gatekeeper will push the latest changes to the central repo with
>> git push central <merge_testing_branch>:master
This command pushes the changes from the local branch <merge_testing_branch> to the "master" branch on the remote repository named "central." The central repository will now have the new baseline version of Jetstream. The gatekeeper will email all members instructing them to pull. All members must pull and use this as their new master! This is done with
>> git checkout master
>> git pull central master
Your master will now be up-to-date along with any branches that are based off of your master. Any branches that you are working on that are not based off of your master, e.g. older branches from earlier in development, should be merged or rebased into/off this new master.
Those group members who were also part of the syncing group should delete their merging branch once they have the new master.
Finally, compile the new version. I recommend doing a clean make first. Remember to set any preferences in the Makefile (e.g. VER, petsc, etc.) before compiling.
>> make clean
>> make
If you have changes that you wish to contribute to the group and you are either one of a few or the only one from the group that is ready to merge, the group code gatekeeper may ask you to test your code individually.
Ensure your changes are commited on your local branch master, and ensure that your code us up to date, i.e. double-check you are on the master branch and pull from the remote repository with
>> git checkout master
>> git pull central master
Ensure that you have PETSC installed (instructions here) as well as TACS and its dependencies (instructions here, here, and here). Then in your Makefile, set
VER=_JSTS
tacs=on
petsc=on
scalapack=on
and run the following commands in your terminal to make a clean version of jetstream for the test suite,
>> cd $HOME/jetstream
>> make clean
>> make tacs
>> make
If that compiled correctly, you are ready to run the test suite. Go to your scratch directory and run the following,
>> cd $SCRATCH
>> bash /project/z/zingg/JSTS/launchJSTS
This will create a new directory, copy over the test suite cases, and submit them to the queue. Once these runs are completed, you can check the results by running
>> bash checkJSTS
in the JSTS directory created in your scratch. Follow the instructions generated at the top of the output to ensure that the results of your test runs match the benchmark cases.
Notify the gatekeeper that your runs passed, and either show them in person or send them screenshots of the output of the checkJSTS script to verify. They will then pull your master branch to theirs (which should be kept clean of developments - alternatively they can make a new branch "merging"), and push it to the remote master using the following commands:
>> git pull /home/z/zingg/<dev's user_name>/jetstream master:master
>> git push central master:master # or merging:master
It is your responsibility to diagonise the reason why the test failed. If you are confident that the new code is correct, the gatekeeper can update the benchmark. Otherwise, something in your recent commits changed the code such that it is producing different outputs to the benchmark test cases, and it is your responsibility to find out why. Remember, this code will live on in perpetuity, so be kind to the students that come after you!
If you need help diagnosing the bug, you can ask the gatekepper for help, but note that they may or may not be able to help you.