Processes to finalize

Development workflow

To propose changes for the master branch of NCAR/MARBL, use the following steps (to begin, we assume that the developer has already forked NCAR/MARBL to his or her own github account):

1. Developer checks out the latest master from NCAR/MARBL on a local machine
2. Developer creates a new branch off of master
   • There is no set naming convention, but it is good practice to name your branch bugfix/[desc_of_bug] if it is a bugfix, enhancement/[desc_of_feature] if it is code cleanup, or science/[desc_of_feature] if it is a new scientific feature. Examples:
     1. To fix a bug where MARBL was still writing some messages to stdout, we used the bugfix/use_status_log branch
     2. To generalize the saved state datatype (the GCM doesn't need to know what field is being saved), we used the enhancement/generalize_saved_state branch
     3. To introduce iron ligands to the library, we used the science/iron_ligand branch
3. [Actual development occurs here, resulting in updated local branch]
4. Testing
   1. At this point, there is no automated test suite for the stand-alone tests but developers should run all regression / unit tests and visually inspect the output
   2. POP developers should run the aux_pop_MARBL test suite in CESM
5. Developer pushes branch from local machine to his or her fork of MARBL
6. Developer issues a pull request

At this point, it is assumed that development is finished and it's time to get the rest of the MARBL team involved. Phase II of development is the following:

1. The developer should organize a code review with other developers
2. Typically the code review will result in a small number of updates; these should be made in the local branch (and tested!) and then pushed back to the github fork. Note that this will automatically update the pull request
3. The developer should make sure the latest master from NCAR/MARBL has been merged onto the local branch (and tested!), and then push that back to the github fork
4. The gatekeeper will merge the branch back to master

There are still some unanswered questions about the process:

1. What testing should be done prior to making a pull request?
   • aux_pop_MARBL is the only test suite we have at the moment
2. Is any additional testing needed before accepting pull request?
3. How do we make sure enough eyes see the code before accepting?
4. We should design a pull-request template (and maybe a commit log template as well); see issue #45

Enforcing coding standards

1. NAG doesn't allow lines to exceed 132 characters - there is a branch on mnlevy1981/MARBL (with a pull request submitted to bring it back to master) that has a script that checks for lines exceeding this maximum, maybe we should add it as a commit hook? Or at least provide it so users can run the check themselves?
2. CESM supports five compilers: intel, gnu, pgi, NAG, and cray. I don't know if ACME supports any additional compilers (IBM?), but we need to verify that code builds on all those platforms (spoiler alert: pgi doesn't work). For developers that don't have access to all those compilers, how do we enforce this?

Update to this: I am going to create a new [public] github repository that contains a suite of scripts to check various measures of code consistency. At that point, I'll update both this wiki page and the main MARBL readme with instructions on how to set up precommit hooks in local checkouts of MARBL - this will make it so that git will not allow you to commit code that violates specific guidelines (such as the 132 character limit). It seems harder, but potentially not impossible, to also have these checks run before accepting any pull requests in github.

Interface design / Documentation

1. What should the interface between GCM and MARBL look like? (Or maybe interfaces?)
2. How will the interface(s) be documented / shared with the public?

Public release repository?

1. Do we want a public-facing repository to push releases to? I'm thinking of something similar to the MPAS set-up, where code stays on the private development repository until it has been written up and submitted for peer review.
   • The github organization named MARBL was already taken (by the Maryland Bioinformatics Labs) when we started looking at github in earnest, but we do own marbl-ecosys