From b4cad770842f1d6ad1854bf49b33f764d3fd15e4 Mon Sep 17 00:00:00 2001 From: Tom Robinson Date: Mon, 30 Sep 2024 10:41:33 -0400 Subject: [PATCH] Updates for documentation clarity --- CODE_STYLE.md | 6 ++++-- CONTRIBUTING.md | 23 +++++++++++++++-------- README.md | 4 +++- 3 files changed, 22 insertions(+), 11 deletions(-) diff --git a/CODE_STYLE.md b/CODE_STYLE.md index 44182e33..e9eebfc8 100644 --- a/CODE_STYLE.md +++ b/CODE_STYLE.md @@ -30,12 +30,14 @@ if(file_exists(fileName)) call open_file(fileObj,fileName, is_restart=.false) ``` * Avoid the use of `GOTO` statements -* Avoid the use of Fortran reserved words as variables (e.g. `DATA`, `NAME`) +* 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 must be in CapitalWord format. +* Type names must be in CapitalWord format and end in either _t or _type. * Variables names must be in underscore_word format. * All member variables must be private. * Doxygen description on the line before the type definition. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8f446d82..f2988b5d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing To libFMS +# Contributing To FMScoupler Thank you for taking time to contribute. @@ -13,11 +13,11 @@ 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 more scrutiny and require more 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. +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 @@ -46,7 +46,7 @@ uphold this code. Please report unacceptable behavior to 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 to scientifically justify the need to make updates at the coupler level** +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. @@ -71,7 +71,8 @@ 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. +to format the message, and include links to references. Any downstream code +updates required for changes should be included in the issue. ## Pull Requests @@ -82,6 +83,12 @@ GFDL schedule that addresses the needs of the GFDL scientists. We follow the 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 diff --git a/README.md b/README.md index 562f2811..9e363b3c 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,9 @@ # Flexible Modeling System (FMS) Coupler Instructions for contribuing to this project can be found in the -[Contribution Guidelines](CONTRIBUTING.md) +[Contribution Guidelines](CONTRIBUTING.md). Contributing to the FMScoupler involves a higher +level of scrutiny and justification.:wq + The Flexible Modeling System (FMS) is a software framework for supporting the efficient development, construction, execution, and scientific interpretation