-
Notifications
You must be signed in to change notification settings - Fork 6
Contributing
First, thanks a lot for considering a contribution to CICE or Icepack!
The central index for CICE repository information is the Resource Index page, which contains links to code, extensive documentation, testing information and procedures, helpful guidelines, and more. CICE and Icepack each have their own set of documentation.
If you still need help getting started using the model after reviewing the model documentation, the first point of contact with the CICE Consortium is the Consortium Community Forum. This forum is monitored by Consortium members and is also open to the whole community for input. Please do not use our issue tracker for general support questions.
We use GitHub issues mainly for confirmed bugs in the model and discussion of Consortium-led development tasks.
If you believe you have found a bug in CICE, please open a thread on the Forum. We will create a GitHub issue if needed.
In your thread, be sure to:
- Document (1) the steps you took, (2) the machine being used, (3) the expected behavior of the model, and (4) its actual behavior.
- If you are running on an unsupported machine and have a porting related problem:
- Talk with your local IT help desk. They will likely be more help than we can be.
- If you are still stuck, then let us know your operating system and version, and provide the
env.<machine>_<compiler>andMacros.<machine>_<compiler>files you are using.
For feature/enhancement proposals, we suggest first opening a new thread on the Forum for discussion with Consortium team members. We want the transition of your new features into our main repositories to be as smooth as possible.
Please review and follow our Code of Conduct and Software Development Practices when contributing code. To get started coding, take a look at the Developer Guide section of the model documentation and other information for developers linked from the Resource Index.
If you are proposing new CICE or Icepack code development as part of a proposal for funding and would like to include a statement of collaboration, please see our statement below:
The CICE Consortium's goal is to accelerate scientific sea ice model development and its transfer into operational use. As such, the CICE Consortium is a vehicle for collaboration as the community continues to use and improve the CICE sea ice model and its column physics package, Icepack. Consortium team members are supported through in-kind FTE contributions by their respective agencies, to maintain the current model for existing and new users, and to assist in incorporating and maintaining new research and development. The Consortium’s codes are open-source with a standard 3-clause BSD license, and a Distribution Policy protects intellectual property rights for shared development code before it is released via a public repository. Scientific review is done by the community in publicly accessible code, leading to further development. Community model developers are responsible for following the Consortium’s Software Development Practices, including thoroughly documenting and testing their new and modified code, with guidance from Consortium members. Consortium team member participation in community code development is contingent upon mutually agreed upon terms and conditions.
CICE uses a forking and Pull Request (PR) workflow, so start by forking the repository to your GitHub account. We use feature branches for development, so please keep your pull requests self-contained, i.e. your pull request branch should be separate from main and should not contain unrelated changes.
A detailed overview of the workflow can be found in the Git Workflow Guide which includes a Git primer for less experienced users and guidance for working with the column portion of the model, Icepack, which is included in CICE as a Git submodule. We strongly recommend you review the Git Workflow Guide.
Any contribution to CICE must be properly tested to ensure that code modifications do not unexpectedly change the model output. This is a prerequisite for a PR to be reviewed. The required level of testing is described briefly in our Software Development Practices, and both CICE and Icepack have thorough testing documentation linked from the Resource Index. For example, a detailed walk-through is available in the End-To-End Testing Procedure section of the User Guide in the CICE documentation.
PRs introducing new features should have corresponding tests added to the base_suite test suite.
We often hear from users that the CICE code is great but the documentation is awesome. Please help us keep it that way by letting us know about weaknesses or errors (through the Forum) and by providing complete documentation for any new code features.
The CICE and Icepack model documentation source is in the doc/source folder of each repository. To make documentation updates easier, opening a pull request automatically triggers a build of the documentation, so the updated docs can be reviewed as part of the PR. When the PR is merged, the online documentation is also automatically updated. We even have documentation about the documentation: the Documentation Workflow Guide has information about syntax, building the documentation locally, and Frequently Asked Questions.
Your pull request will be reviewed by members of the Consortium. You might be asked to polish your PR, add tests or modify documentation before it is merged into the main branch. Please respond to this feedback and feel free to ask questions. Once the reviewers are satisfied with the pull request, it will be merged into the main branch. Any forward development at this point should happen in a new branch.