Page Comparison

Integrator Mailing List

All integrators should be subscribed to the integration email list:   e3sm-integrators@lists.mcs.anl.gov  (Contact Robert Jacob to be added).  This list has a daily posting as to the status of the 'next' and 'master' branches with regards to scheduling pull requests.      

Integrator Roles

The Integrator's role is to take a finished feature branch and integrate it into master, with some care.  The developer of the feature branch assists the integrator.

E3SM Integrators (and github username)

Atmosphere:  Balwinder Singh (singhbalwinder), Wuyin Lin (wlin7), Aaron Donahue

...

Machine file integrators (Machine POCs) not already listed above: Min Xu, Noel Keen, Jason Sarich (Unlicensed), Bibi Mathew, Aaron Donahue (LLNL) (Can integrate any machine-specific changes even if they are the author.)

Integrators know...

1. The overall development goals for the component and where the proposed check-in fits within those plans and the E3SM development timeline.
2. How to run the test suite on a platform.
3. How to conduct a code review.
4. The E3SM Development Reference
5. This Integrator Guide.

Integrators can...

1. Merge code to the master, next or maint permanent branches as appropriate. (Only through pull requests)
2. Reset next branches.
3. Create maint branches.
4. Make tags on the master or maint branches following Branch, Tag, and Version name conventions.
5. Verify bugs and, working with group leads, assign developers to fix them.

Can I merge my branch?

(TODO:  write more detailed instructions)

The answer to this question can basically be found by asking "given the current state of the dashboard AND what has already been integrated to next today, will I be able to tell on tomorrow's dashboard if my branch passed its testing?"

Integrating a Feature Branch.

...

NOTE:  Integrators should never force push to master or next, unless they are rewinding next purposefully and approval has been given to do so. Force pushing to either branch requires project wide emails notifying people what what is going on, and how to ensure they don't run into any issues as a side effect.

Post-cime merging

Moved to /wiki/spaces/SE/pages/36176429

Processing a bug

If you've been assigned to a bug, follow these steps:

1. If the description is not complete, work with the bug reporter, through issue comments, to understand/reproduce bug.
2. Make sure the issue has the "bug" label and at least one component label (atmosphere, land, ocean, etc.).
3. Add ONE of the following additional labels:  duplicate, won't fix, invalid, confirmed
   1. duplicate:  If the bug is a duplicate of another bug, mention the issue number and close the issue.
   2. won't fix:  If the bug is really a user error or not a bug in the ACME source.
   3. invalid:  For issues that shouldn't be in our issues section.
   4. confirmed:  The bug is real.
4. Optional:  Add additional label "Critical" if the bug needs extra attention.  Add label "Minor" if bug fix can be delayed.
5. Assign the bug to a component developer to fix, using their github account name and the "Assignee" menu on the github issue.  Work with group leads if necessary.
6. Optional:  After consulting with group leads, create a JIRA task in your group for fixing the bug.  Use the task id in related commit messages.  See Commit and PR message template and /wiki/spaces/Docs/pages/14385182

Reseting Next

When a new tag is created on master, the next branch should be reset. In order to reset the next branch, an integrator should perform the following steps.

1. Ensure they have the new tag: git fetch origin -p
2. Once they have the new tag, they can reset their local copy of next to the tag
   1. git checkout next
   2. git reset --hard <tag> (e.g. git reset --hard v0.3)
3. After next has locally been reset. They can force push next to origin: git push origin +next

Making a Maintenance Branch

When a new tag is created on master, a new maint branch should be created for that tag. An integrator should perform the following steps to create a new maint branch.

1. Create a new local maint branch off of that tag: git checkout -b maint-<tag> <tag> (e.g. git checkout -b maint-0.3 v0.3)
2. Push the maint branch: git push origin maint-<tag>

Merging Maint to Master

If a maintenance branch received a new feature that also needs to be on master (such as a bug fix), you can merge the maintenance branch to master after the feature has been merged to the maintenance branch.   If this is not possible because the master branch has had to many changes, have the developer issue a second PR to master. 

Creating a Tag on Master or Maint branches

Tags that are created on master or a maint branch should always be annotate tags. Tags are created on specific commits and don't track branches. In order to create a new tag, an integrator should perform the following steps:

1. Determine the hash of the commit that should be tagged (this could be a branch name, if the HEAD of the branch should be tagged)
2. Create a new annotated tag on that commit: git tag -a <tagname> <hash> (again, <hash> can be replaced with a branch name to tag the HEAD of the branch)
3. An editor will come up to write an annotation for the tag. The tag annotation should describe what the tag is for, and preferably a short changelog of what went into the tag relative to the last tag.
   1. In order to summarize the work that went into the tag, an integrator can use the following command: git log --oneline --decorate --first-parent --graph <last_tag>...<hash> (e.g. git log --oneline --decorate --first-parent --graph v0.2...origin/master)
   2. The summary created with the above command shouldn't be placed directly in the annotation. Instead it should be paraphrased to give an idea of the modifications that went into the model.
4. Push the newly created tag: git push origin <tagname>

Additional Information

Role of integration branches.

It is important for integrators to understand the role of the integration branches:

...

In addition to understanding the typical workflow, an integrator should understand the tagging policies defined in Branch, Tag, and Version name conventions

Integrating from a fork

As developers can choose to work in a fork of E3SM-Project/E3SM it's important for all integrators to know what a fork is, and understand how to integrate from a fork.

...

Typical integration can now continue as listed above, using the remote pointing to the developers fork in places of origin.

Example of a successful merge and push to master

This is what you might see if you there are no conflicts.

...

   c355863..8fdf993  master -> master

Resolving merge conflicts

Sometimes when attempting to integrate a feature, an integrator might encounter several merge conflicts they don't know how to deal with. In order to make the job of an integrator easier, they can employ the help of the developer who submitted the pull request using the following steps:

...

• Fetch the history of ACME-Climate/ACME: git fetch origin
• Checkout the target branch: git checkout master (If master is the target. Other targets could be next, maint, or other branches)
• Merge topic branch into target branch: git merge origin/user/component/branch (NOTE: Don't merge the -resolved version)
• Resolve merge conflicts using the -resolved branch: git checkout origin/user/component/branch-resolved -- .
• Finish merge commit, and edit to follow the format described in Commit and PR message template: git commit
• Push merge commit onto target branch in ACME-Climate/ACME: git push origin master

Racy Integration

Two people occasionally attempt to merge at about the same time, in which someone will "lose the race". It usually goes like this: you checkout 'next', pull to make sure you have everything from upstream (you didn't forget this, right?), merge 'my/topic-branch', test, and attempt to push, getting an error like:

...

This keeps both merge commits (which is a record that there was a race, or just clutter) but `git log --first-parent` still produces an accurate and concise summary.

Bypassing hooks

Sometimes when integrating a branch, the branch name is really long which triggers an error using our ACME-Hooks. In this case, the hook can be bypassed after ensuring that your commit message looks correct by issuing the following command:

...