CONTRIBUTING.md

   1 # Contributing To libFMS
   2
   3 Thank you for taking time to contribute.
   4
   5 libFMS is a software framework for supporting the efficient development,
   6 construction, execution, and scientific interpretation of atmospheric, oceanic,
   7 and climate system models.
   8
   9 Contributions to this project are released to the public under the
  10 [projects open source license](LICENSE.md).
  11
  12 What follows is a set of guidelines and how-tos for contributing to libFMS.
  13 These are guidelines, not rules.  Use your best judgement and feel free to
  14 propose changes to this document in a pull request.
  15
  16
  17 Table of Contents
  18 * [Code of Conduct](#code-of-conduct)
  19 * [Quick Start Workflow](#quick-start-workflow)
  20 * [Support](#support)
  21 * [Issues](#issues)
  22 * [Pull Requests](#pull-requests)
  23 * [Tests](#tests)
  24 * [Styleguides](#styleguides)
  25 * [Maintainer Help](#maintainer-help)
  26
  27 ## Code of Conduct
  28
  29 This project and everyone participating in it is governed by the
  30 [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to
  31 uphold this code. Please report unacceptable behavior to
  32 [gfdl.climate.model.info@noaa.gov](mailto:gfdl.climate.model.info@noaa.gov).
  33
  34 ## Quick Start Workflow
  35
  36 1. Create an issue that describes the change, or feature request
  37 2. Fork the project
  38 3. Create a feature branch off an up-do-date `main` branch
  39 4. Update the tests and code
  40 5. Push the commits to your fork
  41 6. Submit a pull request to the `main` branch
  42
  43 ## Support
  44
  45 To get support, open a GitHub issue using the support issue template.  Please be
  46 as descriptive as possible.  See the [Issues](#issues) section for more details.
  47
  48 Support for this project is primarily accomplished via this project’s community.
  49 Additional support may be offered from related communities
  50 (e.g. [MOM6](https://github.com/NOAA-GFDL/MOM6) or by members of the GFDL
  51 [Modeling Systems](https://www.gfdl.noaa.gov/modeling-systems) Group.  The
  52 members of the Modeling Systems group are the main developers and maintainers of
  53 this project.  Modeling Systems is a small group, and our ability to offer
  54 support is limited.  Please be patient when requesting support.
  55
  56 ## Issues
  57
  58 When contributing to this project, please first open an issue using the template
  59 that best matches the change type.
  60
  61 | Template        | Description                                                        |
  62 | --------------- | ------------------------------------------------------------------ |
  63 | Bug             | Report a bug, or unexpected behavior                               |
  64 | Feature Request | A requested feature or change to the code                          |
  65 | Support         |  Request for support.  Please see the [Support](#support) section. |
  66
  67 The issue title should be short and descriptive.  The issue description should
  68 be clear and concise.  Include enough information to help others reproduce the
  69 issue, or understand the change requested.  Use
  70 [GitHub flavored markdown](https://guides.github.com/features/mastering-markdown/)
  71 to format the message, and include links to references.
  72
  73 ## Pull Requests
  74
  75 Submit pull requests for bug fixes, improvements, including tests, or alerts to
  76 particular problems in the code.  We perform merge requests based on an internal
  77 GFDL schedule that addresses the needs of the GFDL scientists.  This release
  78 schedule is better described in the Release Schedule sections.  We follow the
  79 [GitHub fork-pull request workflow](https://guides.github.com/activities/forking/)
  80 workflow, briefly described in the [Quick Start Workflow](#quick-start-workflow)
  81 section.  When creating the pull request, please select a template that best
  82 matches the type of changes.
  83
  84 Please keep the changes in a single pull to be as small as possible to help
  85 reviewer(s) quickly evaluate changes.  If you do have a large update, try to
  86 split the update into small, logical pull requests.  If the update includes code
  87 refactoring, please submit a pull request that includes just the code refactoring.
  88
  89 Once a pull request is created, a member of the Modeling Systems group will
  90 review the changes, and, if necessary, will work with the author of the pull
  91 request to modify their code changes. Note that merging pull requests is
  92 contingent on several factors, including the ability to support the code changes
  93 long-term, portability, and the scope of the impact on the code base. Therefore,
  94 Modeling Systems does not guarantee that all pull requests will be accepted,
  95 even if the changes pass the initial testing phases, and are otherwise correct.
  96
  97 ## Tests
  98
  99 FMS uses TravisCI and gitlab-CI to run build tests for libFMS.  Users may create
 100 unit tests, code coverage tests, and regression tests for new and existing code
 101 in yaml (.yml) files.  Github provides a guide
 102 (https://help.github.com/en/articles/about-continuous-integration) for
 103 implementing CI tests.
 104
 105 ## Code Style
 106 Code updates should follow the coding style for the project, contained in
 107 [CODE_STYLE.md](CODE_STYLE.md).
 108
 109 ## Release Schedule
 110
 111 Releases will be tagged using the format `yyyy.rr[.pp]`, where `yyyy` is the
 112 4-digit year, `rr` is the 2-digit release number, and `pp` is the 2-digit patch
 113 number.  Preliminary releases mean for testing (i.e., code that is still under
 114 development) will be marked `yyyy.rr.alpha.pp` or `yyyy.rr.beta.pp`. Alpha tags
 115 mark code updates that are intended for developers to include in their baseline
 116 regression tests to determine whether the code contains bugs not encountered
 117 during baseline testing. Beta tags are intended for a wider audience of
 118 developers and end users to ensure that their simulations run as expected and
 119 reproduce prior results.