Development Getting Started Guide

Owned by Robert Jacob
Last updated: Apr 07, 2023
5 min read

How to work with the E3SM code base.

  1. 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.  
  2. github account for source code
    1. 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.
    2.   "fork" the model to your own github account. See  https://guides.github.com/activities/forking/


  3. 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.
  4.  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.
    (NOTE: you can skip the next four steps below by running this script https://gist.github.com/douglasjacobsen/3ea4421c0d8ae8c460b0 )
  5. Set up your git environment with these commands:

    1. git config --global user.name “First Last”

    2. git config --global user.email “user@lab.gov”  (NOTE: use the email you registered on github.com)

    3. git config --global push.default nothing
    4. git config --global core.editor ${EDITOR}   (vim, emacs, etc.)

    5. git config --global color.ui true

    6. git config --global core.autocrlf false
    7. git config --global core.safecrlf false
    8. git config --global pull.ff only
  6. 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:<username>/E3SM.git
  7. 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
  8. Setup the commit message template: In directory "E3SM", do: 
    git config commit.template ${PWD}/.git/hooks/commit.template
  9. (Optional but recommended for bash users)
    1. Download and source git-prompt to add branch information to your bash prompt.
    2. Download and source git-completion.bash to enable tab completion of git commands.

      You are ready to start developing! 


        
  10. FOR STAFF:  Make sure there is an Epic corresponding to a group Roadmap associated with your code development.
  11. By default, you will be on the "master" branch.  For new development you will create a new branch.
  12. 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
    1. Update your fork's version of master.  See Development Reference#Keepingyourforkup-to-date. 
    2. (skip if you just did step a.) Ensure your clone is up to date:  git pull --ff-only origin master
      1. If an error is encountered when pulling, talk to an integrator about fixing it
    3. 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
    4. switch your working tree (local copy) to this branch:   git checkout <branchname>
    5. 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.
  13. 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
  14. 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.  
    1. 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.    
  15. 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.
    1. git push origin <branchname>  Anytime you run "git push" you need to be extremely careful that you know exactly what git is going to do (use --dry-run if you're not sure).  
    2. Never run git push without specifying a branchname.  This ensures you push the correct branch (and not the master branch
  16. Periodically run "Developers Test Suite" including your new tests 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



  17. When you are finished with your development, push your branch to github (see step 15)
  18. Run the "Developers Test Suite" one more time. See  Running the tests instructions.  Make sure all tests pass. 
  19. 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





START:  Steps 1-2 are done once per person














SETUP: Steps 3-9 are done once per platform.



















BASIC DEVELOPMENT:  Steps 10-17 are done for each "chunk" of code development.




















FINISHING UP:    Steps 18-20 are done for each "chunk" of code development when you are finished.