This document provides details on ACME development conventions and practices.

...

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.

common -- Items colored in bold black are commands that will be commonly used.

 Project Life Cycle  

Before getting into the git commands related to our workflow, here is an overview of the life cycle of a feature. This can be used to get a big picture that will be broken up in the following steps.

...

Within this diagram, blue dots have associated feature branches that are omitted for the sake of readability. However, each of them followed the same development cycle as the feature that is being focused on in the diagram. Also, red commits are made to next. Both next and master should only be modified by integrators or gatekeepers. 
 

Basic Development

Creating a new branch: new feature

...

• The bug existed in code imported from CESM such as in the initial version added to the repo.
• The bug was introduced prior to v0.3 (the version where the testing is working)

...

Changing Branches

Creating a new branch will not change the current branch that is being worked on in the current working directory.

...

Once you think development is finished on your branch, you should push the branch to the shared repository (a remoteif you haven't already), and submit a pull request (PR) for the integration of your project feature into master. 

A pull request initiates a process to merge your branch into master. The PR and  process process will be documented in github issues in combination with the subsequent code review and via discussion , and the outcome of the pull request.Pull requests should consist of commits that somehow "go together". It's fine if a single PR fixes multiple bugs or provides multiple features but try not to get carried away (it's hard to review a 100-commit, 10 kLOC pull request)comments on the PR.

1. Commit all your changes and push the branch to the shared repository, 
2. go to https://github.com/ACME-Climate/ACME/branches and find your branch.  Click on  "New pull request".
3. You should verify base and compare of your pull request are correct.  The "base" is master and "compare" is your branch.
4. Enter a PR Title:  Make sure the title is 70 characters or less and explains the PR in a "verb noun" format like "add cool new feature". Do not just use the branch name or what is filled in by default.  (If your branch has a single commit, the title of that commit will be the default, but if your branch has multiple commits, the branch name will be the default.)  You should edit the title to make sure it is descriptive enough. DO NOT include github issue #'s or JIRA tasks in the title. Hyperlinking does not work from the title.
5. Write a PR Description.  In the "Write" field, provide a descriptive message of what all the commits in the PR will do together.  The reviewer will review the description as part of the pull request, because the description will be used in the commit message used when the PR is merged to next and master.   See merge commit template in Commit message template.  The integrator may work with you to edit the PR description.  Do not include Confluence URL's in the PR description.
6. Give PR label(s) ('Label' pull down menu).  Add a label for the component this PR involves.  Add the "bug fix" label if this is a bug fix.  Add the label(s) for BFB, non-BFB, CC, FCC, NML as appropriate.
7. Assign a single Integrator to review manage the PR ( use the 'Assignee' pull down menu). 
8. If you want additional reviewers, add them using the Reviewer pull-down menu.  Anyone can be asked to review.
9. When complete, click on "Create pull request".  This will start the code review and the process of moving this feature to master.  
10. After pull request is created, add  the following in the Comments section:
    1. In the first comment, provide a link to the Design Document governing this PR.   See /wiki/spaces/CNCL/pages/25231511.
    2. In subsequent comments.  
       1. Provide information to aid the Integrator in running, testing, and validating feature (but that is too specific to be included in the general PR description). 
       2. Say how the feature was tested.  Example:  "acme_developer on Titan passed".  If a test is expected to fail and required redoing baselines, state that and list the tests that fail.

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 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?

...

Finally, after testing is complete the reviewer is ready to merge your feature into master. When they are doing this, they might run into unexpected merge conflicts they are unable to resolve.

If they do happen to run into this situation, you may be requested to help with the process. The easiest way to help is to create a new branch at the HEAD of the branch your pull request was submitted from. This branch should have the same name as the other branch with -resolved appended to the end. After the branch is created, you can merge ACME-Climate/ACME/master into it, and push the resolved version onto the shared repository. This gives the reviewer a version of the code that is merged and resolved, but allows the reviewer to ensure the history maintains the standards.

...

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.

...

git push <remote-name> <local-branch>:<remote-branch>

...

can be used to write a local branch to a remote branch on the remote pointed to by the name provided. An explicit example would be: 

...