WRF
Code Repository and Release Administration
This
document describes the policies and procedures for maintaining the WRF code
repository and for overseeing releases. Those seeking details on submitting
code to WRF may consult the document “Information for Code Contributors” on the
procedures and requirements for contributing to WRF system. The oversight,
maintenance, and support of the WRF code is handled by the Mesoscale and
Microscale Meteorology (MMM) Laboratory of NCAR.
A.
WRF Committees
1)
Overview
WRF
repository and release management is handled by two committees: the Developers’
Committee and the Release Committee. The Developers’ Committee oversees
additions to, and maintenance of, the repository, while the Release Committee
oversees the new releases to the user community.
2)
Structures and Functions
a)
Developers’ Committee (DC)
The
Developers’ Committee keeps the WRF system code in order through, when
required, review of proposed modifications and contributions to the
repository. Code contributors are required to perform testing, now largely
automated, and provide information on their proposed code commits. The automated
set of tests on code modifications are conducted on pull requests (PRs) to the
WRF GitHub repository.
b)
Release Committee (RC)
The
Release Committee oversees the scheduling, preparation, and issuance of updated
WRF system code in the form of major releases. It compiles a prospective list
(the “release picture”) of additions or modifications (“candidate features”)
offered by developers as contributions to a release. Committee members serve
as the points of contact with developers offering code for the release. The
committee monitors testing, progress, and issues with candidate features. As
the release cycle proceeds, the committee assesses which features can meet the
release schedule given the status of their implementation and testing.
The
Release Committee sets the release schedule, including the timetable for
required notifications, code submissions, and release branch testing. The
Release Committee provides information on releases to the WRF user community at
the annual WRF workshop.
The
Release Committee has members from various groups involved in WRF code
development and user support, and they serve as points of contact for the major
areas of the WRF system, such as software and physics. The Release Committee
is chaired by a scientist in NCAR’s Mesoscale and Microscale Meteorology (MMM)
Laboratory, as MMM is responsible for support of the primary WRF system to the
community.
B.
Repository and Release Management
1)
Repository
a) 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. The repository is managed and maintained such that it always contains
the most current, working, and theoretically-releasable revision of the WRF
model, plus a fully-recoverable history of past revisions and developer
notations.
The
directory structure contains the trunk, which is the repository itself; tags,
which are a series of development snapshots of the trunk; plus a number of branches.
Prior to a planned release date, a branch is created for the code to be
released. From the date of this cutting off of the release branch, the branch
will only accept bugfixes and corrections for the code to be released.
The
contents of the repository on Github are open to public download. Any
unsanctioned use of the repository code (such as accessing another scientist's
branch, releasing new versions for which a user is not the author, etc.) is
prohibited.
b) Responsibilities of the Developers’
Committee
The
Developers’ Committee oversees the management and maintenance of the WRF
repository.
The
purposes of the Developers’ Committee are as follows.
·
Shepherd
new development
The Developers’ Committee provides an
interface to outside developers and facilitates incorporation of new or
enhanced features and functionalities in WRF.
·
Quality
assurance and investment preservation
The Developers’ Committee ensures that the
develop branch of WRF is in order and in principle releasable.
·
Process
management
The Developers’ Committee is responsible
for establishing and following processes for maintaining the WRF repository and
for evaluating, incorporating, and assuring the quality of new features and
functionalities. DC members review PRs and the documentation required.
·
WRF
Physics Review Panel interaction
The Developers' Committee communicates
with the WRF Physics Review Panel when the panel has reviewed a proposed new
physics package. The panel provides a recommendation to the DC on whether to
accept the package, and the DC makes the decision on whether to admit the new
code.
It
is a proposing developer’s responsibility to perform all required testing and
provide all required documentation in proposing a commit. The proposing
developer must ensure that the proposed change is correct and that its effects on
other parts of the model are described. A developer whose code is impacted by
a proposed commit may request a code review and may work with the originating
developer to run tests to verify that the proposed change does no harm.
Disagreements about changes to scientific or forecast results must be resolved
before code or code changes can be committed. Developers have effective veto
power over changes that affect aspects of the WRF system for which they have
primary responsibility.
2) Releases
a)
Responsibilities of the Release Committee
The
WRF Release Committee oversees the process of major releases. This includes
scheduling; review of information on submitted features; review of the status
of new code contributed or proposed; making determinations on release items;
and coordination of release preparation, testing, and communication. The
Release Committee may determine that a major release is warranted based on the
annual release cycle or on the needs of the user community. The Release
Committee sets the major release timeline and communicates release information
to the WRF community.
b)
Types
(i) Major
Major
releases are made on an approximately annual basis. Major releases reflect the
addition of new and improved capabilities and, occasionally, significant
structural changes warranting a new model version number. With a major
release, run-time options can change, and default behavior can be modified.
(ii)
Minor
Minor
releases primarily address bug fixes. Minor releases are determined and
overseen by the director of wrfhelp, and their preparation and support
are the responsibility of wrfhelp. Minor release material usually
consists of the modified routines or files and accompanying documentation or
information posted on the “Known Problems” web page under the WRF users' site.
Most modifications to the source code in a minor release should fix software
errors, provide code clean-up, or address a problem that justifies an immediate
fix. Information on bug fixes is posted on the web.
c) Nomenclature
Releases
are numbered as Version a.b or a.b.c, and, in emergency situations, a.b.c.d.
The first digit reflects major restructuring, development, or upgrades. As an
example, a new version of WRF with a different leading digit might not ingest
or correctly process data from a version of the code with a different leading
digit.
The
second digit reflects a major release not amounting to a new version, typically
done annually. With changes to the second digit, the new version will offer
new features, and there will be backward compatibility with older input files.
The new version may also modify the meaning of run-time options.
The
third digit reflects bug fixes/minor releases. A release using a fourth digit
would be a minor release issued to correct quickly a significant bug; these
release are rare.
3) Activity status and release procedures
With
respect to the typical annual cycle of major releases, there is baseline
activity that occurs independent of any release-specific work and the pre-release
period for release-directed code preparation. Baseline activity includes the
reviewing of proposed commits, integration of contributions, and PR and other
testing. PR testing is conducted via an automated system and is done to ensure
accuracy and confidence in parallel results.
The
pre-release status period begins 5–6 months prior to a scheduled major release,
when the major release cycle begins. In this period the release schedule is
determined, the release picture is compiled and regularly updated, and the
committee and developers work toward the cutoff of the release branch and the
branch code’s subsequent testing.
a) Baseline activity
After
a WRF major release, commits should be proposed to the develop branch, with automatic
regression testing conducted on submission of PRs. The purpose of this regression
testing is to identify software errors (e.g., bit-for-bit differences) and
failures to compile or run. These tests are short and do not attempt to detect
or analyze differences in the forecast skill. Proposed code modifications are
made via PRs to GitHub. These include an explanation of the modification and
list the touched files.
b) Pre-release
activity
(i) Release minus 6 months (R-6m)
In
this time frame the Release Committee (RC) has a first meeting to discuss the
next major release. The RC identifies a major release as a combination of
candidate features and a proposed date. The RC considers for the release those
capabilities they have been notified of and that can be integrated into the
repository prior to the branch cutoff. The release picture is the list
of features and modifications considered for the release.
(ii) Release minus
3–4 months (R-3-4 m)
In
this period developers intending to contribute code for the next major release must
have provided their code if they want it considered for inclusion in the
release branch. The code must conform to the WRF coding standards described in
“Information for WRF Code Contributors".
At
approximately the 3-month point, the release branch is cut off. All new code
and features to be included in the release must be in the repository at this
time. After the branch is made, the changes allowed to it are only those
necessary for the release’s development, such as bug fixes or modifications for
difficulties with new feature interaction. Even with the release branch
created, the develop branch remains open to commits. Code proposed for commit
after release branch cutoff is directed to the develop branch.
In
this time frame, meetings of the Release Committee are held approximately every
2 weeks.
Checks
on new features to be included in the release are discussed by the RC. The
decision to either (i) drop a feature that will not be ready within the
schedule or (ii) adjust the release schedule so that a crucial feature is
included in the release is made by the committee.
(iii) Release
minus 2 months (R-2m)
The
RC may decide upon non-automated tests to review the forecast skill of the new
release code. Examples are case study runs. As tests are run, the results are
discussed at the committee meetings.
Within
this period, the release branch code may be offered the code to friendly users
and vendors for pre-release testing.
Except
for the accommodation of bug fixes, in this period the branch remains frozen:
only corrections for problems identified during testing on the code to be
released may be introduced. Errors introduced into existing code are fixed,
while larger-scale restructuring is redirected to the trunk, which remains open
to development. Changes to documentation files and inline documentation,
however, are freely accepted.
(vii) Release
minus 2 weeks (R-2w)
The
final modifications for code identification, documentation, and release
readiness are committed. The code is staged for final release. The release
preparation list for WRF user support includes web page updates, documentation
updates, and user notification.
c) Release
procedures
The
plans and schedule for the next major release follow the initial Release
Committee meeting in the R‒6 mos. timeframe. These include a list of the
significant candidate items and a timetable.
At
the annual WRF Users’ Workshop, the previous major release is detailed in a
presentation. Any significant known plans for the next major release may be
included in the talk as well.
4) Code Contribution
a)
Baseline activity
New
developments, code improvements, and contributions of bugfixes continue for the
trunk between releases. Code contributors are responsible for:
1) ensuring their
code has passed the automated testing, and correcting it until it has;
2) ensuring that the
code has been submitted with the required commit information and that the code
conforms to the WRF coding standards;
3) warning the
Developers’ Committee about any limiting underlying assumptions or possible
code conflicts; and
4) documentation.
Contributors
are responsible for supplying documentation on the code they provide, which may
be in the form of a web page or adequate (as deemed by the DC) README files or
inline documentation.
As
described under the "WRF Physics Review Process" page (http://www2.mmm.ucar.ed/wr/users/physics_review.php), for proposed
new physics packages the WRF Physics Review Panel must review the submitted
materials. It then makes a recommendation on whether to accept the new
package. This is simply a recommendation, and the DC has the final say.
b)
Pre-Release Activity
(i) Release minus 3 months (R–3m)
In
this period, all code sought to be considered for the release by developers
should have been committed to the repository or be in submission in the form of
PRs. While there is no guarantee that any code will get into a given release,
these requirements assist in the preparation of the release branch, which will
be cut off at approximately R
3 mos. The code
must conform to the requirements described in “Information for WRF Code
Contributors" (http://www2.mmm.ucar.edu/wrf/docs/contrib_info.pdf). It is the
responsibility of the developers to make sure that the deadline is met.
By
the release branch cutoff date all of the proposed new features for the release
must have been put into the branch. As the release gets nearer, general bug
fixes or modifications to address issues uncovered in testing are still
eligible for inclusion. New items arriving after the branch cutoff date are
simply proposed for commit to the trunk.
(ii) Release minus 1 month (R–1m)
In
this stage the only acceptable changes are those pertaining to testing of the
frozen code. During this last month of testing, final results for additional
architectures, case studies, and timing studies are considered. The RC reviews
the information to ascertain that the release is on schedule or that remedial
action is required.
5/25
