2.3. Code and Configuration Standards

2.3.1. General Policies

  • Platform-specific settings should be handled only through configuration and modulefiles, not in code or scripts.

  • For changes to the scripts, ush, or jobs directories, developers should follow the NCO Guidelines for what is incorporated into each layer.

  • Developers should ensure that their contributions work with the most recent version of the ufs-srweather-app, including all the specific up-to-date hashes of each subcomponent.

  • Modifications should not break any existing supported capabilities on any supported platforms.

  • Update the RST documentation files where appropriate as part of the PR. If necessary, contributors may update the documentation in a subsequent PR. In these cases, the contributor should open an issue reflecting the need for documentation and include the issue number and explanation in the Documentation section of their initial PR.

  • Binary files will no longer be merged into the develop branch. A binary file is defined as a “non-text” file and can include *.png, *.gif, *.jp*g, *.tiff, *.tar, *.tgz, *.gz, *.mod, *.o, and executables. If a binary file needs to be staged in the ufs-srweather-app repository, please add it to the wiki’s repository. The command to clone the ufs-srweather-app’s wiki repository is git clone https://github.com/ufs-community/ufs-srweather-app.wiki.git. Users with write access to the wiki repository can add the files here and link them to the documentation as needed. Users who do not have write access to the wiki repository should reach out to @MichaelLueken and/or note this in their pull request so that the files can be added.

2.3.2. SRW Application Guidelines

General Coding Standards:

  • The ufs-srweather-app repository must not contain source code for compiled programs. Only scripts and configuration files should reside in this repository.

  • All bash scripts must explicitly be #!/bin/bash scripts. They should not be login-enabled (i.e., scripts should not use the -l flag).

  • MacOS does not have all Linux utilities by default. Developers should ensure that they do not break any MacOS capabilities with their contribution.

  • All code must be indented appropriately and conform to the style of existing scripts (e.g., local variables should be lowercase, global variables should be uppercase).

External Components

  • All externals live in a single Externals.cfg file.

  • Only a single hash will be maintained for any given external code base. All externals should point to this static hash (not to the top of a branch).

  • All new entries in Externals.cfg must point only to authoritative repositories. In other words, entries must point to either a ufs-community GitHub organization repository or another NOAA project organization repository.

    • Temporary exceptions are made for a PR into the develop branch of ufs-srweather-app that is dependent on another PR. When the component PR is merged, the contributor must update the corresponding ufs-srweather-app PR with the hash of the component’s authoritative repository.

Build System

  • Each component must build with CMake

  • Each component must build with Intel compilers on official Level 1 platforms and with GNU or Intel compilers on other platforms.

  • Each component must have a mechanism for platform independence (i.e., no hard-coded machine-specific settings outside of established environment, configuration, and modulefiles).

  • Each component must build with the standard supported NCEPLIBS environment (currently spack-stack).

Modulefiles

  • All official platforms should have a modulefile that can be sourced to provide the appropriate Python packages and other settings for the platform.

  • Each SRW component must build using the common modules located in the modulefiles/srw_common file.

2.3.2.1. Workflow Coding Standards

Python Coding Standards:

  • All new Python workflow contributions should come with an appropriate environment YAML file (similar to environment.yaml, graphics_environment.yaml, and aqm_environment.yaml).

  • Keep the use of external Python packages to a minimum for necessary workflow tasks. Currently, these include f90nml, pyyaml, and Jinja2.

Workflow Design: Follow the NCO Guidelines for what is incorporated in each layer of the workflow. This is particularly important in the scripts directory.

Management of the Configuration File: New configurable options must be consistent with existing configurable options and be documented in UsersGuide/CustomizingTheWorkflow/ConfigWorkflow.rst. Add necessary checks on acceptable options where applicable. Add appropriate default values in config_defaults.yaml.

Management of Template Files: If a new configurable option is required in an existing template, it must be handled similarly to its counterparts in the scripts that fill in the template. For example, if a new type of namelist is introduced for a new application component, it should make use of the existing jinja framework for populating namelist settings.

Namelist Management: Namelists in ufs-srweather-app are generated using a Python tool and managed by setting YAML configuration parameters. This allows for the management of multiple configuration settings with maximum flexibility and minimum duplication of information.