FMS and FMScoupler Release Process

FMS Release Process

FMS and FMScoupler follow the same release schedule, version numbers, and process. These two repositories comprise the foundation for all FMS models run by the scientists at the Geophysical Fluid Dynamics Laboratory (GFDL). As FMS is used in other models across NOAA and other public projects, the process the code managers of the FMS and FMScoupler repositories follow for when code merges are performed is outlined here.

Contributing to FMS and FMScoupler

This document describes how the code managers determine which and when pull requests are merged into their target branch. This is not a guide on how to contribute to the FMS and FMSCoupler projects. Information on how to contribute to the FMS and FMScoupler projects can be found in the CONTRIBUTING.md documents contained in their respective repository

Our Commitment

We strive to work with all developers contributing to FMS and FMScoupler to get their contributions to be part of the projects. However, as FMS and FMScoupler are the base infrastructure for most of the GFDL models and model components and that the Unified Forecast System uses FMS and GFDL model components, our priority is to ensure those groups have the code updates required to perform their work. Thus, at times we may choose to delay an update to allow the repository managers and the Modeling Systems Division at GFDL time to test and evaluate other issues and pull requests. Our goal is to be clear when these delays may occur. However, from time to time unforeseen delays may occur and we request patience from all contributors to these projects.

Release Planning

How releases are tagged is explained in the repository’s contributing guides. Each release will be tracked using a GitHub organization project. The repository code managers will decide on a schedule for each release. As part of setting the release schedule, the code managers will work with the members of the GFDL Modeling System Division to determine what goals have been established for the release. Once the schedule and release goals are determined, the code managers will review all open issues and pull requests to determine which additional items can be included in the release. Once decided, the issue or pull request will be added to the project and milestone set. Periodically, the code managers will meet to discuss the issues and pull requests. During the meeting, they will review and, if needed, adjust the priority of open issues and pull requests. The order of the issues and pull requests in the project columns will be used to determine the priority -- the higher in the column the higher the priority. As needed, the code managers will assign issues and pull request reviews.

Project Layout

Each FMS and FMScoupler release project will have the following columns:

• To Do
• Issues in progress
• PRs in progress
• Review in progress
• Reviewer approved
• To merge
• Done
• Rejected

The To Do and Issues in progress are used to track issues. When issues are added to the project, they will begin in the To Do column. As issues are assigned, the code managers will move the issue from To Do to Issues in progress. If a closed issue in the project is reopened, it will be placed in the Issues in progress column. When an issue is closed, it will be placed in the Done column.

The Done and Rejected columns are to track issues and pull requests that are completed. All closed issues, even those not completed, will be placed in the Done column. Pull requests that have been merged will be moved to the Done column. If a pull request is closed with unmerged commits, it will be placed in the Rejected column.

The PRs in progress column will contain all new pull requests that are added to the project. Pull requests will remain in this column until a reviewer approves or requests changes. If changes are requested, the pull request will move to the Review in progress column. Once a pull request is approved by all reviewers, the pull request will be moved to the Reviewer approved column.

During code manager review meetings, the code managers will review all pull requests found in the Review approved column, and determine which will be merged. Accepted pull requests will be placed in the To merge column and a schedule created for the merge to be performed.

From time to time, the code managers will reach out to the developers of a particular pull request to better understand the purpose of the pull request. This can cause delays when a pull request is merged. We strongly recommend all pull requests and associated issues contain as much information as possible.

Minting a Release

Up to a few weeks before a release, the repository managers will only perform pull requests that address issues discovered during the Modeling System Division tests. After the Modeling Systems Division has run all required tests, the code managers with the help of the Modeling Systems Division members, will determine when a release is ready. A few days before the release, the code managers will ensure the CHANGELOG.md files are up to date, and adjust the version number in the build configuration files (e.g. configure.ac, CMakeLists.txt). When the release is ready, the code managers will create an annotated git tag with the release name following the description in the project’s contribution guide. The code managers will also create a GitHub release. The creation of the GitHub release is to allow those watching the FMS and FMScoupler projects to know a new release is available.