From 9bf5658009d81d4c565c61515c7934d68fd343ad Mon Sep 17 00:00:00 2001 From: Tom Robinson <33458882+thomas-robinson@users.noreply.github.com> Date: Fri, 24 Jan 2025 15:53:19 -0500 Subject: [PATCH] docs: adds documents for guidelines on contributing (#149) --- CODE_OF_CONDUCT.md | 69 +++++++++++ CODE_STYLE.md | 287 +++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 154 ++++++++++++++++++++++++ README.md | 5 + 4 files changed, 515 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CODE_STYLE.md create mode 100644 CONTRIBUTING.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..97a779e9 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,69 @@ +# Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others’ private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, or to ban temporarily or permanently any +contributor for other behaviors that they deem inappropriate, threatening, +offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at climate.model.info@noaa.gov. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project’s leadership. + +## Attribution +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), +version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html diff --git a/CODE_STYLE.md b/CODE_STYLE.md new file mode 100644 index 00000000..6d44244c --- /dev/null +++ b/CODE_STYLE.md @@ -0,0 +1,287 @@ +# Coding Style + +## General + +* Trim all trailing whitespace from every line (some editors can do this + automatically). +* No characters. +* Supply a header for each file with a description of the file and the author(s) + name or GitHub ID. +* A copy of the [Gnu Lesser General Public License](https://www.gnu.org/licenses/lgpl-3.0.en.html) + must be included at the top of each file. +* Documentation should be written so that it can be parsed by [Doxygen](http://www.doxygen.nl/). +* All variables should be defined, and include units. Unit-less variables should be marked `unitless` +* Provide detailed descriptions of modules, interfaces, functions, and subroutines +* Define all function/subroutine arguments, and function results (see below) +* Follow coding style of the current file, as much as possible. + +## Fortran + +### General + +* Use Fortran 95 standard or newer +* Two space indentation +* Use `KIND` parameters from platform_mod of libFMS +* Never use implicit variables (i.e., always specify `IMPLICIT NONE`) +* Lines must be <= 120 characters long (including comments) +* logical, compound logical, and relational if statements may be one line, + using “&” for line continuation if necessary: + ```Fortran + if(file_exists(fileName)) call open_file(fileObj,fileName, is_restart=.false) + ``` +* Avoid the use of `GOTO` statements +* Avoid the use of +[Fortran keywords](https://fortranwiki.org/fortran/show/Keywords) +as variables including `NAME` (e.g. `DATA`) +* Avoid the use of `COMMON` blocks + +### Derived types + +* Type names with more than one word must be in CapitalWord format and end in either _t or _type. +* Variables names with more than one word must be in underscore_word format. +* All member variables must be private. +* Doxygen description on the line before the type definition. +* Inline doxygen descriptions for all member variables. + +## Functions +* If a function has a result variable, it should be declared on its own line, + and the variable should not be declared with a specific intent. +* Inline doxygen descriptions for all arguments, except the result variable. +* Doxygen description on the line(s) before the function definition. This must + specify what the function is returning using the `@return` doxygen keyword. + +## Blocks +* terminate `do` loops with `enddo` +* terminate block `if`, `then` statements with `endif` +* Label large blocks or multiple nested blocks + +## OpenMP + +* Directives should start at the beginning of the line, and be in lowercase. +* All openMP directives should specify default(none), and then explicitly list + all shared and private variables. +* All critical sections must have a unique name. + +## Precision +* Precision of all real arguments are explicitly defined as `real(kind=r4_kind)`, + `real(kind=r8_kind)`, or as any other precision parameters defined in platform_mod of libFMS. +* The precision of real numerical values should be consistent with the precision + of the associated variable. For example, if the variable `a` has been declared + as r8_kind, then `a=1.4_r8_kind` is acceptable. The following, a=1.4 and a=(1.4,kind=r8_kind), + are not acceptable since the numerical value of 1.4 will be represented in the default precision + set by the compiler. +* The precision of integers do not need to be explicitly defined and can be determined at compile time. +* If the precision of integers are explicitly defined, they are defined with the precision parameters, + _e.g._ i4_kind, i8_kind, found in platform_mod of libFMS. + +## Macros +* All letters in the macro names are capitalized +* All macro names end with an underscore "_" +* All precision related macro names start with the letters "FMS" +* Macro names should be unique to each module. For example, + `FMS_AU_KIND_` is used in axis_utils_mod. + `FMS_HI_KIND_` is used in horiz_interp_mod + +## .fh and .inc files +* The .fh header files contain macro definitions. +* If the .fh files contain mainly precision related macro definitions, the files + should be named with `_r4.fh` and `_r8.fh` extensions in the include subdirectory found + in the module directory. These .fh files are `#include`-ed at the end of the .F90 module files. +* For precision related .inc files, the .inc files contain the procedure definitions and are + `#include`-ed at the end of both *_r4.fh and *_f8.fh files. These .inc files are located in the + same include subdirectory as the .fh files. See below for details. +## Fortran Example + +```Fortran ./example.F90 file + +!*********************************************************************** +!* GNU Lesser General Public License +!* +!* This file is part of the GFDL Flexible Modeling System (FMScoupler). +!* +!* FMScoupler is free software: you can redistribute it and/or modify it under +!* the terms of the GNU Lesser General Public License as published by +!* the Free Software Foundation, either version 3 of the License, or (at +!* your option) any later version. +!* +!* FMScoupler is distributed in the hope that it will be useful, but WITHOUT +!* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +!* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +!* for more details. +!* +!* You should have received a copy of the GNU Lesser General Public +!* License along with FMScoupler. If not, see . +!*********************************************************************** + +!> @file +!! @brief Example code +!! @author +!! @email gfdl.climate.model.info@noaa.gov + +module example_mod + use FMS, only r4_kind, r8_kind, i4_kind, i8_kind, util_func1 + implicit none + private + + public :: sub1 + public :: func1 + public :: ex_subroutine + + interface ex_subroutine !< generic interface block. When the user + module procedure ex_subroutine_r4 !! calls ex_subroutine, the compiler checks + module procedure ex_subroutine_r8 !! the input arguments and invokes either + end interface ex_subroutine !! ex_subroutine_r4 or ex_subroutine_r8 + !! ex_subroutine_r4/8 are generated by the preprocessor + !! which requires example_r4.fh, example_r8.fh, and + !! example.inc files + + !> @brief Doxygen description of type. + type,public :: CustomType + private + integer(kind=i4_kind) :: a_var !< Inline doxygen description. + real(kind=r8_kind),dimension(:),allocatable :: b_arr !< long description + !! continued on + !! multiple lines. + endtype CustomType + + contains + + !> @brief Doxygen description. + subroutine sub1(arg1, arg2, & + & arg3) + real(kind=r4_kind),intent(in) :: arg1 !< Inline doxygen description. + integer(kind=i8_kind),intent(inout) :: arg2 !< Inline doxygen description. + character(len=*),intent(inout) :: arg3 !< Long inline doxygen + !! description. + + arg1=2.456_r4_kind + end subroutine sub1 + + !> @brief Doxygen description + !! @return Function return value. + function func1(arg1, arg2) result(res) + integer(kind=i4_kind),intent(in) :: arg1 !< Inline doxygen description + integer(kind=i4_kind),intent(in) :: arg2 !< Inline doxygen description + integer(kind=r8_kind) :: res + + res=real(arg1,r8_kind) * 3.14_r8_kind + end function func1 + +#include "example_r4.fh" !< These two header file contains the macro definition +#include "example_r8.fh" !! and an "#include example.inc" where the procedure + !! is defined. See below. +end module example_mod +``` +```Fortran ./include/example_r4.fh file +!*********************************************************************** +!* GNU Lesser General Public License +!* +!* This file is part of the GFDL Flexible Modeling System Coupler. +!* +!* FMScoupler is free software: you can redistribute it and/or modify it under +!* the terms of the GNU Lesser General Public License as published by +!* the Free Software Foundation, either version 3 of the License, or (at +!* your option) any later version. +!* +!* FMScoupler is distributed in the hope that it will be useful, but WITHOUT +!* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +!* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +!* for more details. +!* +!* You should have received a copy of the GNU Lesser General Public +!* License along with FMScoupler. If not, see . +!*********************************************************************** + +!> @file +!! @brief Example _r4.fh file containing macro definitions +!! @author +!! @email gfdl.climate.model.info@noaa.gov + +#undef FMS_EX_KIND_ +#define FMS_EX_KIND_ r4_kind + +#undef EX_SUBROUTINE_ +#define EX_SUBROUTINE_ ex_subroutine_r4 + +#include "example.inc" !< example.inc file contains the procedure definition +``` +```Fortran ./include/example_r8.fh file +!*********************************************************************** +!* GNU Lesser General Public License +!* +!* This file is part of the GFDL Flexible Modeling System Coupler. +!* +!* FMScoupler is free software: you can redistribute it and/or modify it under +!* the terms of the GNU Lesser General Public License as published by +!* the Free Software Foundation, either version 3 of the License, or (at +!* your option) any later version. +!* +!* FMScoupler is distributed in the hope that it will be useful, but WITHOUT +!* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +!* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +!* for more details. +!* +!* You should have received a copy of the GNU Lesser General Public +!* License along with FMScoupler. If not, see . +!*********************************************************************** + +!> @file +!! @brief Example file _r8.fh file containing macro definitions +!! @author +!! @email gfdl.climate.model.info@noaa.gov + +#undef FMS_EX_KIND_ +#define FMS_EX_KIND_ r8_kind + +#undef EX_SUBROUTINE_ +#define EX_SUBROUTINE_ ex_subroutine_r8 + +#include "example.inc" !< example.inc file contains the procedure definition +``` +``` Fortran ./include/example.inc file +!*********************************************************************** +!* GNU Lesser General Public License +!* +!* This file is part of the GFDL Flexible Modeling System Coupler. +!* +!* FMScoupler is free software: you can redistribute it and/or modify it under +!* the terms of the GNU Lesser General Public License as published by +!* the Free Software Foundation, either version 3 of the License, or (at +!* your option) any later version. +!* +!* FMScoupler is distributed in the hope that it will be useful, but WITHOUT +!* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +!* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +!* for more details. +!* +!* You should have received a copy of the GNU Lesser General Public +!* License along with FMScoupler. If not, see . +!*********************************************************************** +!> @file +!! @brief Example .inc file containing subroutine definitions/declarations +!! @author +!! @email gfdl.climate.model.info@noaa.gov + +!> The macro EX_SUBROUTINE_ gets replaced by the preprocessor +!! as ex_subroutine_r4 (as defined in the example_r4.fh file) and +!! as ex_subroutine r8 (as defined in the example_r8.fh file) + +subroutine EX_SUBROUTINE_(arg1, arg2, arg3) + real(FMS_EX_KIND_), intent(in) :: arg2 !< FMS_EX_KIND_ gets replaced by the preprocessor + real(FMS_EX_KIND_), intent(out) :: arg1 !< FMS_EX_KIND_ gets replaced by the preprocessor + integer(i4_kind) :: arg3 + integer, parameter :: lkind=FMS_EX_KIND_ !< kind parameter local to the subroutine + + arg1 = arg2 / 4.0_lkind !< GCC does not like 4.0_FMS_EX_KIND_. Thus, the + !! parameter lkind is declared and used. + +end subroutine EX_SUBROUTINE_ +``` + +## C/C++ + +### General +* C code is written in GNU style. Each new level in a program block is indented + by 2 spaces. Braces start on a new line, and are also indented by 2 spaces. +* See the [Gnome C coding style guide](https://developer.gnome.org/programming-guidelines/stable/c-coding-style.html.en) + for more information diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..f9f80fe1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,154 @@ +# Contributing To FMScoupler + +Thank you for taking time to contribute. + +Contributions to this project are released to the public under the +[projects open source license](LICENSE.md). + +What follows is a set of guidelines and how-tos for contributing to FMScoupler. +These are guidelines, not rules. Use your best judgement and feel free to +propose changes to this document in a pull request. For information on code style +please review the [code style guidelines](CODE_STYLE.md). + +## High Bar for Contribution + +Because the FMScoupler is used by all of the models and all of the model +components at GFDL, updates face enhanced scrutiny and require enhanced +justification and testing. The additional step of setting up a meeting +with Modeling Systems Division (MSD) is required for all updates to ensure +that the updates are required at the coupler level. MSD will reject updates +that should/could be made in a component model. + + +## Table of Contents +* [High Bar for Contribution](*high-bar-for-contribution) +* [Code of Conduct](#code-of-conduct) +* [Quick Start Workflow](#quick-start-workflow) +* [Support](#support) +* [Issues](#issues) +* [Pull Requests](#pull-requests) +* [Tests](#tests) +* [Styleguides](#styleguides) +* [Maintainer Help](#maintainer-help) + +## Code of Conduct + +This project and everyone participating in it is governed by the +[Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to +uphold this code. Please report unacceptable behavior to +[gfdl.climate.model.info@noaa.gov](mailto:gfdl.climate.model.info@noaa.gov). + +## Quick Start Workflow + +1. Create an [issue](#issues) that describes the change, or feature request +2. Fork the project +3. Create a feature branch off an up-do-date `main` branch +4. Update the tests and code +5. Push the commits to your fork +6. Submit a [pull request](#pull-requests) to the `main` branch +7. **Set up a meeting with GFDL Modeling Systems Division and any other itnerested parties to scientifically justify the need to make updates at the coupler level**. +8. Fulfill requests for changes + +Note: Step 7 is an extra necessary step. + +## Support + +To get support, open a GitHub issue using the support issue template. Please be +as descriptive as possible. See the [Issues](#issues) section for more details. + +Support for this project is primarily accomplished via this project’s community. +Additional support may be offered from related communities +(e.g. [MOM6](https://github.com/NOAA-GFDL/MOM6)) or by members of the GFDL +[Modeling Systems](https://www.gfdl.noaa.gov/modeling-systems) Group. The +members of the Modeling Systems group are the main maintainers of +this project. Modeling Systems is a small group, and our ability to offer +support is limited. Please be patient when requesting support. + +## Issues + +When contributing to this project, please first open an issue. +The issue title should be short and descriptive. The issue description should +be clear and concise. Include enough information to help others reproduce the +issue, or understand the change requested. Use +[GitHub flavored markdown](https://guides.github.com/features/mastering-markdown/) +to format the message, and include links to references. Any downstream code +updates required for changes should be included in the issue. + +## Pull Requests + +Submit pull requests for bug fixes, improvements, including tests, or alerts to +particular problems in the code. We perform merge requests based on an internal +GFDL schedule that addresses the needs of the GFDL scientists. We follow the +[GitHub fork-pull request workflow](https://guides.github.com/activities/forking/) +workflow, briefly described in the [Quick Start Workflow](#quick-start-workflow) +section. + +Any changes that are required for a PR in the FMScoupler should be linked. Merges +should take place downstream first in order to ensure new dependencies are +available. Changes made to componenet models that change calls in the +FMScoupler must include changes to corresponding null/data models in order to +maintain the automated build tests. + +Please keep the changes in a single pull to be as small as possible to help +reviewer(s) quickly evaluate changes. If you do have a large update, try to +split the update into small, logical pull requests. If the update includes code +refactoring, please submit a pull request that includes just the code refactoring. + +Once a pull request is created, a member of the Modeling Systems group will +review the changes, and, if necessary, will work with the author of the pull +request to modify their code changes. Note that merging pull requests is +contingent on several factors, including the ability to support the code changes +long-term, portability, and the scope of the impact on the code base. Therefore, +Modeling Systems does not guarantee that all pull requests will be accepted, +even if the changes pass the initial testing phases, and are otherwise correct. + +## Reviewing Pull Requests + +When reviewing a pull request, members of MSD should look for the following: + +- Design + - Does the code change belong in the FMScoupler library or does it better belong elsewhere such as a component repository or FMS? + - Could existing routines/modules be utilized to reduce redundancy? + - Temporary changes/fixes meant to be removed should be avoided whenever possible +- Functionality + - Does this PR do what is intended (and stated) + - Are the changes good for both end-users and developers? + - Will the code change impact existing end-users needlessly? +- Complexity + - Are the changes easily understood by the reader / reviewer? +- Testing + - Code changes should include a test program or a modification to a test program to ensure the code is covered by the test suite +- Comments + - Inline comments for complex code segments or intricacies to make the purpose of the code reasonably clear +- Style and Consistency + - Code should follow the [syle guide](CODE_STYLE.md) in general, but should also be consistent to the file the change is made in +- Documentation + - If a PR changes the behaviour or instructions, accompanying documentation should also change +- Thoroughness + - Reviews should be done line by line, and the surrounding context/file should be taken into account + +Comments on pull requests should be courteous and constructive, giving useful feedback and explanations for why changes should be made. See the [code of conduct](CODE_OF_CONDUCT.md) for more information. + +## Tests + +FMScoupler uses GitHub Actions to test FMScoupler. Users may create +unit tests, code coverage tests, and regression tests for new and existing code +in yaml (.yml) files. Github provides a guide +(https://help.github.com/en/articles/about-continuous-integration) for +implementing CI tests. + +## Code Style +Code updates should follow the coding style for the project, contained in +[CODE_STYLE.md](CODE_STYLE.md). + +## Release Schedule + +Releases will be tagged using the format `yyyy.rr[.pp]`, where `yyyy` is the +4-digit year, `rr` is the 2-digit release number, and `pp` is the 2-digit patch +number. Preliminary releases mean for testing (i.e., code that is still under +development) will be marked `yyyy.rr.alpha.pp` or `yyyy.rr.beta.pp`. Alpha tags +mark code updates that are intended for developers to include in their baseline +regression tests to determine whether the code contains bugs not encountered +during baseline testing. Beta tags are intended for a wider audience of +developers and end users to ensure that their simulations run as expected and +reproduce prior results. diff --git a/README.md b/README.md index cfd4e456..96d8f02c 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,11 @@ # Flexible Modeling System (FMS) Coupler +Instructions for contribuing to this project can be found in the +[Contribution Guidelines](CONTRIBUTING.md). Contributing to the FMScoupler involves a higher +level of scrutiny and justification. + + The Flexible Modeling System (FMS) is a software framework for supporting the efficient development, construction, execution, and scientific interpretation of atmospheric, oceanic, and climate system models.