Forrest M. Hoffman
Updated: March 2, 2010
The iESM Project is using the Mercurial distributed source control managment tool for managing revisions to software source code from multiple developers on the project. This page offers some helpful hints and guidelines for using Mercurial for code development for the iESM Project. Please send questions, comments, suggestions, and corrections to Forrest M. Hoffman (forrest@climatemodeling.org).
Mercurial is a free, distributed source control management tool. It is presently available for Microsoft Window, GNU/Linux, MacOS X, OpenSolaris, and other systems. More information about Mercurial, the software, and installation instructions can be found at http://mercurial.selenic.com/.
Return to Topics.
After installing Mercurial on your system, you should setup your identity and e-mail address. On Unix/Linux, this is accomplished by creating a file called .hgrc in your home directory containing your real name and e-mail address at a minimum. For example,
| File: ~/.hgrc |
|
where you enter your own name and e-mail address.
Return to Topics.
The iESM software repositories are available at https://www.climatemodeling.org/repos/iesm_software/. Access to the repositories requires use of SSL-encryption and a username and password. If you need a username/password combination for access to the iESM software repositories, contact Forrest M. Hoffman (forrest@climatemodeling.org).
Return to Topics.
Yes there are. Most of the software contained in the iESM repositories are unreleased, development versions of models, including the NCAR Community Climate System Model (CCSM) and the PNNL/JGCRI Global Change Assessment Model (GCAM). Only developers for the iESM project are granted access to the software repositories, and those developers must agree to use the code only for project development purposes. Both CCSM and GCAM have access policies that must be upheld by iESM developers. The CCSM Repository Access Policy is available here. The code cannot be shared with others, exchanged for other code, or used for research outside of the project simulations agreed to by the iESM Principal Investigators. Any violation of these access policies will result in the violator losing all access to the repositories.
Return to Topics.
Simply clone the desired repository listed on the webpage at https://www.climatemodeling.org/repos/iesm_software/. For example, to obtain the GCAM code do the following:
|
Now you have a copy of the entire repository, including all branches and changesets, on your local machine. Changes can be made and those changes can be committed to your local repository as you see fit. Once you are ready to share your changes, pull down the latest version of the repository, update your code to the head of the branch or tip, commit these changes, and push your changesets up to the server.
Return to Topics.
From any directory within your repository, you can commit changes at any time. This will generate a new changeset in your local repository, but it will not automatically push changesets up to the server. Since other developers or users will not see these changesets until they have been pushed, it is safe to commit changes frequently for more incremental development. In order to push changesets up to the respository server after committing changes, see below. It's always a good idea to pull down any new changesets and update your local code, especially if you are not the only developer making changes on your branch or if you are modifying the tip. For information about about pulling down changesets, see below.
In order to commit changes to your local repository, simply do the following:
|
This command should start an editor to allow the developer to enter documentation about his changes. These commit messages should be as descriptive as possible and follow the convention outlined below.
Return to Topics.
When committing code modifications in Mercurial (see above), an editor should start to allow the developer to enter documentation about his changes. These commit messages hould be as descriptive as possible to allow other developers and users understand exactly what changes were made any why. Our convention for commit messages consist of a one-line summary of changes, a blank line, and free-form text describing the details of the changes being committed. This text should be entered above lines of text produced by Mercurial, which should be left in the file when you save it and exit.
|
Return to Topics.
Climate and Carbon Cycle Research