CESM POP2 Developers' Guidelines

Document Date: 28 March 2012

Revised in this version: code documentation information in Section 8, CCSM references were changed to CESM, and old links were commented out.

Previous Version

The procedures contained in this guide, which apply only to the CESM version of pop2, are intended to

These guidelines comprise a "living document," subject to occasional revisions and updates as procedures evolve or requirements change.

  1. Collaboration
  2. Developers are encouraged to contact local OMWG pop2 developers at any point during the development cycle to resolve questions regarding these guidelines. Phone calls, hallway discussions, or quick, informal meetings are all good ways to maintain communications during the development process.

  3. Design Review
  4. Prior to undertaking new, significant pop2 developments, developers are encouraged to engage with local Ocean Model Working Group (OMWG) members to discuss their prospective work. Informal design discussions can result in valuable, early feedback that can often ultimately reduce the time of the development cycle.

  5. Code Base
  6. New pop2 developments should originate from a version as close to the most recent pop2 trunk tag as is reasonably possible. Using an older, outdated code base increases the complexity of the code review and merging processes, and it increases the probability of errors. Merging new developments based on a highly outdated code base into the most recent pop2 trunk code is the responsibility of the developer.

  7. Coding Guidelines
  8. As closely as possible, all pop2 code developments should adhere to the following coding guidelines.

    These guidelines are complicated by the fact that the present CESM pop2 code is undergoing a transition from LANL pop2-based coding style to the new LANL hypop/pop3-based style. In order to avoid internal inconsistencies, new code added to existing CESM pop2 modules should follow the coding style of the existing module; new modules should emulate the LANL hypop/pop3 modules.

  9. Testing
  10. Developers are responsible for testing their codes.

  11. Code Review
  12. When new developments are ready to be considered for the pop2 trunk, the developer schedules a code review/walkthrough with local OMWG members. To accomodate developers at remote sites, a walkthrough may be held via telecon or other such means.

    The Code Review consists of the following elements:

    A Code Review meeting can often be completed in a one-hour session, although sometimes, more complicated reviews do take longer. The code reviewers generally ask questions, suggest or request changes or additional tests, and remind the developer of overlooked issues, elements, or interactions.

    Often, a Code Review results in additional work that needs to be done by the developer prior to check-in. This might include additional error-detection code, new namelist control variables, additional comments, or other code changes or improvements. If the changes are extensive, the developer is expected to re-test, then schedule a follow-up session to review the new changes and test results with the reviewers.

    These review sessions are intended to educate pop2 users, result in better code, and reduce errors. They are conducted in an informal, collegial manner, and although discussions are often spirited, professional conduct is the norm.

    At the end of a successful Core Review cycle, the OMWG Co-chairs -- with input from the OMWG members -- determine if the code can be checked into the pop2 repository trunk.

  13. Activation of New Code
  14. The OMWG Co-chairs determine if new code on the pop2 trunk will be activated "out of the box." This determination typically is made with input from the OMWG, so a developer may be requested to present their results at an OMWG meeting prior to a decision.

    It is possible that new code will be approved for the trunk, but with the code deactivated for the default, out-of-the-box configuration. This allows the developer to continue developments, testing, or even production runs while the option is under consideration.

  15. Trunk Check-in and Documentation
  16. Following the successful completion of the Code Review, the code will be checked onto the trunk of the pop2 repository in a timely manner by the pop2 gatekeeper and documented on the CESM pop2 documentation web page. The local OMWG Co-chair will prioritize the check-in by the repository gatekeeper. Typically, once all code and documentation are available, check-in will occur within days of approval for trunk check-in. During periods of intense scientific developments, such as the finalizing of the scientific code to be used in integrations for the IPCC Assessment Report, science modifications may take priority over software engineering mods.

    Tags are documented in the $SVN/pop2/ChangeLog file, which is provided by the developer, following the existing template.

  17. Input Datasets
  18. If the new developments require new pop2 input datasets, these datasets must follow the inputdata filenaming conventions. All new pop2 input datasets must be fully documented, following the guidelines in the finenaming document.