How to work with the E3SM code base.
- Read the Development Big Picture page. Note in particular the recommended philosophy of working with branches is different than what you may be used to.
- github account for source code
- Sign up for a free account at http://github.com. Choose a username that is close to your real name (first initial and last name) and edit your github profile to include your real name. Your code is work product like a publication and you should have your name on it.
- Log on to the platform on which you want to do E3SM development. Our supported platforms will have all the necessary software available and have configurations defined to build and submit the model. NOTE: Make sure the python executable is in your path. This might be automatic or might require adding a module depending on the platform. DO NOT try to build or run within a conda environment.
- Install an ssh key from that platform to your github account. See these instructions and note you can skip step 2 if you already have an ssh key on your machine.
( - Set up your git environment with these commands:
git config --global user.name “First Last”
git config --global user.email “user@lab.gov” (NOTE: use the email you registered on github.com)
- git config --global push.default nothing
- git config --global core.editor ${EDITOR} (vim, emacs, etc.)
git config --global color.ui true
- git config --global core.autocrlf false
- git config --global core.safecrlf false
- git config --global pull.ff only
- Clone your fork of the repository to your development machine. This will create a directory called "E3SM" with the code.
git clone --recursive git@github.com:/E3SM.git - Clone the repository hooks: while still in the E3SM directory, do:
rm -rf .git/hooks; git clone git@github.com:E3SM-Project/E3SM-Hooks.git .git/hooks - Setup the commit message template: In directory "E3SM", do:
git config commit.template ${PWD}/.git/hooks/commit.template - (Optional but recommended for bash users)
- Download and source git-prompt to add branch information to your bash prompt.
- Download and source git-completion.bash to enable tab completion of git commands.
You are ready to start developing!
- FOR STAFF: Make sure there is an Epic corresponding to a group Roadmap associated with your code development.
- By default, you will be on the "" branch. For new development you will create a new branch.
- Create a new topic branch for your development: The following command assumes you are on the master branch, change 'master' to the branch name you're using if it's different
- Development Reference#Keepingyourforkup-to-date.
- (skip if you just did step a.) Ensure your clone is up to date: git pull --ff-only origin master
- If an error is encountered when pulling, talk to an integrator about fixing it
- Create your topic branch for your development: FOLLOW THE E3SM BRANCH NAME CONVENTIONS!. Create the branch in your repository, branching from master: git branch <branchname> master
- switch your working tree (local copy) to this branch: git checkout <branchname>
- To ensure you are working on the correct branch, run "git branch" which will show all your local branches and list a "*" by the branch you are currently on.
- Before doing any development, create baselines for any tests you will be using to verify your changes, and place these baselines in a directory you will use to test your branch. At a minimum, this should be baselines for the e3sm_developer test suite. This is a good idea even if you are not making answer-changing code modifications, since the baseline files for the master branch can be changed by other merges while you are working. For information on generating baselines, see Generating new baseline files for a topic branch
- Start editing your code and commit changes to your local repository. (e.g., after making changes, do: git add <files> ; git commit). See Commit and PR message template for how to make a commit message.
- If you have any issues compiling or running the code, check with the POC for the platform you are using: /wiki/spaces/ED/pages/1867951. The POC is responsible for ensuring E3SM tests can run on supported platforms and will be knowledgeable about system specific quirks and features.
- Once you have committed at least one change locally, and verified that you can still build, push your branch to your github repository. You may not be done but this will allow others to follow and contribute to your work.
- Periodically run "Developers Test Suite" and confirm All Tests Pass. If you want to be very careful, you'd run this after every commit. Basic instructions for running and test suite are in Running the tests
- When you are finished with your development, push your branch to github (see step 15)
- Run the "Developers Test Suite" one more time. See Running the tests instructions. Make sure all tests pass.
- Go to your fork on github and make a Pull Request.
Remaining steps will be led by an Integrator. If you know who the Integrator should be, make them the "Assignee" on the PR. If you would like additional people to review, select their github ids under "Reviewers". (The Integrator will review and so does not also need to be added as a "Reviewer".
Your feature is not done and you are not finished with development until the Integrator moves your changes to the "master" branch.
Pay attention to the comments on the PR. You may have to respond to reviewer requests for changes. The Integrator may ask you for help or to make more changes in response to testing.
Further and more detailed instructions can be found in the Development Reference.
If you're new to git, see the Git Tutorial page