Protocol for GEOSldas Pull Requests

Developers must adhere to this protocol to have their changes adopted in future releases.

The GEOSldas repository has two protected branches, develop and main. Generally, new features and bug fixes are first merged into the develop branch and are subsequently merged from develop into main, from where new releases are issued.

A key piece of information is whether source code modifications reproduce binary identical results in the LDAS Nightly Tests. If so, the modifications are considered "zero-diff". This should be true for all trivial and structural changes.

---

Step 1: Open GitHub "issue(s)"

[Skip this step for trivial changes or if asked by the GEOSldas team lead to open a pull request.]

Open a GitHub "issue" to ensure communication across the GEOSldas team and coordination with the GCM developers. Be aware that some features or fixes may have to wait while other priorities are addressed in the main development stream.

a) In the GEOSldas repository, open a GitHub "issue" (i.e., not a "pull request"):

• Describe the planned feature, bug fix, or other change.
• Affix the appropriate GitHub label(s).
• Assign the "issue" to the GEOSldas team lead.

IMPORTANT: Proceed only after concurrence from the GEOSldas team lead.

b) Open a matching issue in the GEOSgcm_GridComp repository (only if your changes impact the GEOSgcm_GridComp repository).

---

Step 2: Update your branch

Make sure your GEOSldas and GEOSgcm_GridComp branches are up-to-date with the respective "develop" branches.

Use git rebase if you have never shared your branch with anyone, and have not yet pushed it to GitHub:

% git checkout develop
% git pull origin
% git checkout <feature-branch>
% git rebase develop

Otherwise, use git merge:

% git checkout develop
% git pull origin 
% git checkout <feature-branch>
% git merge develop

In either case, you need to resolve conflicts, if any, and commit again.

---

Step 3: Determine if, or verify that, changes are zero-diff

This step is required for all except trivial changes.

a) Conduct GCM tests described in the GEOSgcm_GridComp Wiki (only required if GEOSgcm_GridComp was modified):

• https://github.com/GEOS-ESM/GEOSgcm_GridComp/wiki/Zero-diff-changes
• https://github.com/GEOS-ESM/GEOSgcm_GridComp/wiki/How-to-Run-GEOS-Zero-Diff-Tests

Not all of the GCM tests may be needed. Coordinate with the GEOSldas and GEOSgcm_GridComp gatekeepers.

b) Conduct GEOSldas tests (always required, even if only GEOSgcm_GridComp was modified):

• https://github.com/GEOS-ESM/GEOSldas/wiki/LDAS-Nightly-Tests

If your changes are not zero-diff, never assume that they are ok. Such changes always require approval by the GEOSldas team lead.

---

Step 4: Create (draft) pull request(s)

Create matching draft pull requests for the GEOSldas and GEOSgcm_GridComp repositories. The latter pull request is needed only if your changes impact GEOSgcm_GridComp.

• Create a draft pull request (see drawdown option provided with green button on 2nd page in the process).
• Use a descriptive title (not the branch name).
• Add comments about the problem and solution (or refer to the description of the linked "issue", if created in Step 1 above).
• Affix appropriate labels. Must indicate whether "0-diff" or "not 0-diff".
• Make sure the pull request points to the develop branch as the base.
• If the pull request is contingent upon other pull requests, affix the label "Contingent - Do Not Approve".

These steps can all be edited after the pull request has been created. Do not create a new pull request if something needs changing.

Check for merge conflicts. If any, resolve conflicts, commit your branch again, and push to GitHub. Note that merge conflicts may be caused by the pull request mistakenly pointing to the main branch.

---

Additional considerations

• Draft pull requests provide a forum for discussion and development. At the same time, the gatekeepers know not to worry about merging. Change the status to "ready for review" only when the gatekeepers should get involved, that is, after full testing and approval by the science developers and code owners.

• The head of the develop branch may have changed by the time the GEOSgcm_GridComp and GEOSldas gatekeepers are ready to merge your pull request. Usually this will not affect zero-diff changes, but you may be asked to merge the latest develop branch into your branch again and repeat the verification steps above.

• Keep in touch with and listen to the gatekeepers. Communication is paramount to success.