WRF Code Repository and Release Administration¶
This document describes the policies and procedures for maintaining the WRF code repository and for overseeing releases. For details on procedures and requirements for submitting code to WRF, see Information for Code Contributors. WRF code oversight, maintenance, and support is handled by the Mesoscale and Microscale Meteorology (MMM) Laboratory of NSF NCAR.
WRF Code Management Committees¶
WRF repository and release management is handled by two committees:
Developers’ Committee : oversees additions to, and maintenance of, the repository
Release Committee : oversees new releases to the user community
Developers’ Committee (DC)¶
The Developers’ Committee (DC) keeps the WRF system code in order through review of proposed modifications and contributions to the repository. Code contributors are required to perform testing (largely automated), and provide information on their proposed code commits. The automated tests on code modifications are conducted on pull requests (PRs) to the WRF GitHub repository.
Release Committee (RC)¶
The RC establishes the release schedule, including notification deadlines, code submissions, and release branch testing. They inform the WRF user community about releases at the annual Joint MPAS & WRF Users’ Workshop.
The WRF RC, composed of representatives from WRF development and support, acts as the main point of contact for key areas of the WRF system. Chaired by an NSF NCAR/MMM scientist, the committee is responsible for ensuring community support for the primary WRF system.
Repository Management¶
Definition, structure, and access¶
The WRF repository is the store of code constituting the WRF modeling system and software infrastructure (code and meta-code, build scripts, testing mechanisms and datasets, documentation, etc.), maintained under a software management system. It contains the latest working and theoretically-releasable version of the WRF model, along with a fully-recoverable history of past revisions and developer notations.
The repository consists of three main components:
Trunk : which is the repository itself
Tags : a series of development snapshots of the trunk
Branches : used for parallel development efforts
Prior to a release, a dedicated branch is created from the trunk. Following this, only bug fixes and necessary corrections are applied to ensure stability of the release.
The Github repository contents are publicly downloadable. However, unauthorized use of the repository code is prohibited. This includes accessing other users’ branches or releasing new versions without being the original author.
Developers’ Committee Responsibility¶
The DC manages and maintains the WRF repository. Its purpose is as follows:
Shepherd new development : The DC serves as an interface to external developers, facilitating in the integration of new or enhanced features and functionalities.
Quality assurance and investment preservation : The DC ensures the WRF develop branch is in order and, in principle, releasable.
Process management : The DC manages the WRF repository, including establishing processes for maintenance, evaluating and integrating new features, and ensuring quality through PR reviews and documentation.
WRF Physics Review Panel interaction : The DC receives recommendations from the WRF Physics Review Panel on proposed new physics packages. The DC then decides whether to accept the new code.
Developers proposing code commits are responsible for all required testing and documentation, ensuring the change is correct and its effects on any part of the model are described. Developers whose code is impacted can request code reviews and collaborate on tests. Scientific disagreements must be resolved before committing code. Developers have veto power over changes affecting their areas of responsibility.
Release Management¶
Release Committee Responsibilities¶
The WRF Release Committee (RC) manages major releases, including scheduling, feature review, code status, release item decisions, and coordination of preparation, testing, and communication. Based on the annual cycle or user needs, the RC determines if a major release is necessary, sets the timeline, and informs the WRF community.
Types of Releases¶
Major Release¶
Major releases occur annually, introducting new features, improvements, and significant structural changes that warrant a new model version number. They may includechanges to run-time options and default behavior.
Minor Releases¶
Minor releases, overseen by the wrfhelp director, and prepared and supported by wrfhelp members, primarily address bug fixes with modified routines, documentation, or information on the Known Problems web page. Minor releases typically fix software errors, provide code clean-up, or address a problem that justifies an immediate fix.
Nomenclature¶
Releases are numbered as Version a.b.c (and in emergency situations, a.b.c.d), where
a : reflects major restructuring, development, or upgrades, and may be incompatible with data from a previous version of the code
b : signifies an annual major release with new features and backward compatibility, possibly with altered run-time options
c : reflects bug fixes and minor updates
d : this fourth digit is rarely used for urgent significant bug fixes
Activity Status and Release Procedures¶
Throughout the year, baseline activities like reviewing changes, integrating contributions, and automated testing to ensure accuracy and confidence in parallel results occur regardless of specific releases or pre-release code preparation.
The pre-release phase for a major release begins 5-6 months prior, marking the beginning of the major release cycle. During this time, the schedule is set, the release picture is maintained, and the committee and developers prepare for the release branch cutoff and subsequent code testing.
Baseline activity¶
After a WRF major release, commits should be proposed to the develop branch. Automatic regression testing on submitted PRs checks for software errors (e.g., bit-for-bit differences) and compilation/run failures. These short tests do not assess forecast skill. Modifications are proposed via GitHub PRs, and include explanations and lists of touched files.
Pre-release activity¶
Release minus 6 months (R6m)¶
During this time frame, the RC’s holds its initial meeting for the next major release, which involves identifying candidate features and a target date. The RC considers proposed capabilities that can be integrated before the branch cutoff. This list of features and modifications under consideration is the “release picture.”
Release minus 3-4 months (R3-4 m)¶
For code contributions to be considered for the next major release, developers must have provided their code by this point as a PR to the GitHub release branch, and the code must conform to the standards described in Information for WRF Code Contributors.
Around the 3-month mark, a release branch is created, requiring all release features to be finalized. Only bug fixes and necessary integration changes are permitted on the release branch afterward. The develop branch remains active for new commits. Code submitted after the release branch cutoff is directed to the develop branch.
In this time frame, the RC meets bi-weekly to review features proposed for the release. They decide whether to remove incomplete features or adjust the schedule to include critical ones.
Release minus 2 months (R2m)¶
The RC may use non-automated tests, like case studies, to assess new release forecast skill. Results are discussed at meetings. The code may be given to friendly users and vendors for pre-release testing during this time.
During this period, the branch is frozen except for bug fixes identified during release testing. Existing code errors are fixed, while larger-scale restructuring is directed to the open trunk. Changes to documentation are permitted.
Release minus 2 weeks (R-2w)¶
Final code modifications, documentation, and release readiness are complete. The code is staged for release. WRF user support preparations include updating the webpage and documentation, and notifying users.
Release procedures¶
Following the initial RC meeting (R-6 mos. timeframe), the plans and schedule for the next major release, including significant candidate items and a timetable, are devised.
At the annual Joint MPAS and WRF Users’ Workshop, details of the most recent major release are presented, including any significant known plans for the next major release.
Code Contribution¶
Baseline activity¶
Code development, improvements, and bug fix contributions continue between releases. Code contributors are responsible for:
ensuring their code passes automated testing;
ensuring the code submissions include required commit information;
ensuring the code conforms to WRF coding standards;
informing the DC of any limiting underlying assumptions or potential code conflicts; and
comprehensive documentation.
Contributors must supply documentation on their provided code, which may be formatted as a web page, README files (deemed adequate by the DC), or inline documentation.
Proposed physics packages must be reviewed and recommended for approval by the WRF Physics Review Panel, who then forwards their recommendation to the DC for final approval. See WRF Physics Review Process for details.
Pre-Release Activity¶
Release Minus 3 Months (R-3m)¶
By this period, code proposed for the release should either be already committed to the repository, or pending commit (as a PR). It is the developer’s responsibility to ensure their code is submitted by the deadline and conforms to the requirements described in Information for WRF Code Contributors.
Though release approval is not guaranteed, these guidelines facilitate preparation of the release branch, which is forked from the trunk at approximately R-3 mos. By this cutoff date, all proposed new features must be in the branch, while bug fixes and fixes addressing issues discovered during release testing are still eligible for inclusion. New features proposed after this date may still be committed to the trunk, but are not included in the upcoming release.
Release minus 1 month (R-1m)¶
During this stage,
only code changes that address problems discovered during release testing will be considered for the code release;
final results for additional architectures, case studies, and timing studies are considered;
the RC confirms the release schedule or determines the need for remediation.