Page Comparison

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.
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 a JIRA task associated with your code development.  This will be referenced in the commit message.
11. By default, you will be on the "master" branch.  For new development you will create a new branch.
12. To 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. 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
    2. Create your topic branch for your development:  FOLLOW THE E3SM BRANCH NAME CONVENTIONS!
    3. 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. Update MPAS Components and other submodules: git submodule update --init --recursive
       1. Note: The URL for submodules may change in the future.  If this happens, git does not automatically update the URL of the submodule for you.  As long as the URL that your submodule refers to contains the commit being requested for the submodule, this is fine.  However, if you get an error saying the commit was not found, you may need to update the URL used by your local submodule to the one updated and stored in .gitmodules.  This can be done with the command: git submodule sync   If this is needed, it is a one-time operation that is only needed when the URL to which a submodule refers to changes.
          
    6. 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 Testing.
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.  We no longer use ChangeLog so commit messages are important.
    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, push your branch to the main 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. Add tests for your new feature following E3SM unit test framework (NOT YET IMPLEMENTED)
17. Periodically run "Developers Test Suite" including your new tests and confirm All Tests Pass.  Basic instructions for running the Developers Test Suite are in Testing
    
    

    ---

    
    
    
18. When you are finished with your development, push your branch to github (see step 18)
19. Run the "Developers Test Suite" if it is supported on your platform.  See /wiki/spaces/ED/pages/1867951 table and Testing instructions.  Make sure all tests pass. 
20. Go to our github site and make a Pull Request.  

Remaining steps will be led by an E3SM Integrator.  Your feature is not done until the Integrator moves your changes to the "master" branch.  Pay attention to the comments on the PR.  The Integrator may ask you for help or to make more changes in response to testing or reviews.

Further and more detailed instructions can be found in the Development Reference.
 

If you're new to git, see the Git Tutorial page