Quick Guide:

We use git and github.com
We use a merge-based workflow
Feature branch names should be all lower-case with dashes and have this pattern: <github username>/<source code area or component>/<feature-description>
Make good commit messages. See Commit and PR message template
Use testing system to test your branch prior to creating a PR
When creating a PR, make the title and description follow the Commit and PR message template
1. Use the "Assignee" menu on the PR to assign an Integrator.
2. Use the "Reviewer" menu on the PR to assign additional reviewers
3. Add labels
Work with the assigned integrator to bring the PR to master.

How to work with the E3SM code base: step-by-step

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
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/
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.
(NOTE: you can skip the next four steps below by running this script https://gist.github.com/douglasjacobsen/3ea4421c0d8ae8c460b0 )
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
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
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)
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!
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 "master" 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
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.
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.
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.
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
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
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

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.

Browser not supported