Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
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.comSubmit a ticket to the SE/CG Testing & CI Support Help Desk and ask to be added to the ACME private organization on github. Include your Confluence account name so Wade Burgess can verify you're a member of ACME. OR . 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.
- "fork" the model to your own github account.
- Log on to the platform on which you want to do E3SM development. See Available Platforms for a description of available machines. 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:
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 git@githubclone --recursive git@github.com:E3SM-Project<username>/E3SM.git (Or clone your fork to you development machine). Get the source code for submodules needed by E3SM. change directory to E3SM and do:
git submodule update --init - 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.
cd components/mpas-source/src/core_ocean
./get_cvmix.sh
./get_BGC.sh
If you don't and you use passphrases, you'll have to babysit the build and enter your passphrase when prompted. Note these commands should probably be run whenever MPAS-O is updated in case of new cvmix or BGC versions
You are ready to start developing!
- FOR STAFF: Make sure there is a JIRA task an Epic corresponding to a group Roadmap associated with your code development. This will be referenced in the commit message.
- By default, you will be on the "master" branch. For new development you may want to either (1) create your own branch off of "master" or a "maint" branch or (2) work on a branch that someone else has already created.
- To switch your working tree (local copy) to a pre-existing branch:
- look for remote branch names: git branch -r or see Model versions and tags
- Run: git checkout --track <remote branchname>
- Ensure your checkout is up to date: git pull --ff-only
- Update MPAS components and other submodules: git submodule update --init
To create 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
- Update your fork's version of master. See 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 . 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>Update MPAS Components and other submodules: git submodule update --init
- 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.
- 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.
- If you have any issues compiling or running the code, check with the POC for the platform you are using: Configuration Management/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.
- 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).
- Never run git push without specifying a branchname. This ensures you push the correct branch (and not the master branch)
NOTE: Do NOT merge your own branch. DO NOT PUSH THE MERGE PULL REQUEST button.
Remaining steps will be led by an E3SM Integrator. Your 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 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
START: Steps 1-3 2 are done once per person
SETUP: Steps 43-12 9 are done once per platform.
BASIC DEVELOPMENT: Steps 1310-21 17 are done for each "chunk" of code development.
FINISHING UP: Steps 2218-25 20 are done for each "chunk" of code development when you are finished.