This document provides details on E3SM development conventions and practices.

NOTE:

This document does not discuss the use of forks. If a developer understands and prefers to use a fork, it is recommended that they make use of forks.

Introduction

...

important -- Items colored in red mean they are important, and should not be ignored.

one time -- Items colored in green are commands to be issued once per machine.

repo once -- Items colored in orange are commands to be issued once per local repository.

...

Your PR is not finished until it has been merged to master by the Integrator.

This document can be used to help with pull request related issues.

...

1. Check the github entry for the PR and make sure it has a good title and description, correct labels and a comment with a link to the Design Document.   A PR can not be merged to next or master unless it has a Design Document with Phase 1 and 2 completed. See /wiki/spaces/CNCL/pages/25231511.
2. Look at the code changes either on github or using:  git log --reverse -p master.. on your checked out copy of the branch.
   1. Does new code hold up to visual inspection for code quality?    Look over code changes for glaring mistakes or code style issues (e.g. useful comments, reasonable subroutine lengths, new code in an existing file follows conventions of that file).
   2. Check to see if the description of the code changes in the PR match the actual changes.  Make sure nothing unrelated to the PR was committed accidentally.
   3. Although they can't be changed, see if commit messages on the branch follow the Commit and PR message template and let the developer know if they can not.  Consider asking the developer to squash commits to clean up the history.
      
   4. Have tests been added or suggested that exercise this feature?
   5. Does code run on all platforms after integration into next?

...

Before communicating with remotes, you might want to add or remove remotes. In order to add and remove remotes the git remote command can be used. The two uses are as follows:

git remote add remote-name protocol:address/to/repo # Creates a remote

git remote remove remote-name # Removes a remote

In order to communicate with remotes, there are three actions. push, pull, and fetch.

...

You will need to keep the master branch within your fork of E3SM up to date with main version.  Update as often as you want but always before you start new development or if you want to try a test PR on your fork.

We'll refer to the version of E3SM at https://github.com/E3SM-Project/e3sm as the "upstream" version.

First you'll need to add the upstream repo as a remote in a local clone of your fork.

Go to any local clone of your fork and do the following:

...

MacBook-Air.local[104]: git remote -v
origin	git@github.com:rljacob/E3SM.git (fetch)
origin	git@github.com:rljacob/E3SM.git (push)
upstream	git@github.com:E3SM-Project/E3SM.git (fetch)
upstream	git@github.com:E3SM-Project/E3SM.git (push)

Now you can proceed to update your local copy of master.

First fetch the branches (including master) from the upstream

git fetch upstream

Checkout out your fork's version of master.

...

If you see messages like this:

Untracked files:
  (use "git add <file>..." to include in what will be committed)
 components/cam/
 components/clm/
 components/mpas-source/

Those are old submodule locations (because you are updating an old fork).  Delete them with "rm -rf components/cam".

If you see messages like:

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
 modified:   externals/kokkos (new commits)
 modified:   externals/scorpio (new commits)
 modified:   externals/scorpio_classic (new commits)

Those are new submodules.  Update them with "git submodule update --init --recursive".

At this point, "git status" should say something like

On branch master
Your branch is ahead of 'origin/master' by 5124 commits.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

You can now push your updated master to your fork on github

git push origin master

...

Use the "Sync" button on your fork.

Avoid Routine Merges From Master

...

• "frequent pulling of the \[master] into a development branch will add a certain amount of randomness to that branch; this randomness is not particularly helpful for somebody who is trying to get a feature working. It also increases the chances that another developer who ends up in the middle of the series while running a bisect operation will encounter unrelated bugs."
• A branch has a specific purpose. A topic branch 'add-frotz' would be about adding a new 'frotz' feature and shouldn't do anything else.  When you merge from master, you declare that all the other unrelated changes done on 'master' in preparation for the next release somehow bring 'add-frotz' closer to the goal of the 'frotz' topic. That is usually not true
• Unnecessary merges and similar repository clutter reduces the ability to summarize, audit, notice bugs in review, and find bugs after the fact.  Keeping clean history is not difficult.  It requires a little bit of discipline on the part of integrators and developers, but it's a small price to pay for the time saved and improved quality/reliability.

There are some cases where merging from master (or better, a tagged version of master) can make sense.  The rule of thumb for any merge is that if you can clearly describe what you are merging and why that merge is necessary for your branch to be completed, then it's fine to merge.    For example, you might need a feature on master (some crucial functionality, not just a build system updates) to complete the feature on your branch.   Integrators may ask you to merge from master to help resolve conflicts during a PR integration.  But before merging from master, try one of the other ways to get features from other peoples development described in Incorporatinganotherbranchontoyourbranch.

...