-
Notifications
You must be signed in to change notification settings - Fork 18
Governance and Development Workflow for ESM Standard Names
This page describes the governance of the ESM Standard Names dictionary, including procedures for making changes and how they will be approved and adopted.
Note that more detailed rules about Standard Names are contained in the repository itself: https://github.com/ESCOMP/ESMStandardNames/blob/main/StandardNamesRules.rst
The ESM Standard Names governance committee is made up of members representing each project. We will seek to have at least two members from each project: a primary and one or more alternates.
Primary: Michael Kavulich
Alternate(s): Dom Heinzeller, Jesse Nusbaumer
Primary: Dom Heinzeller
Alternate(s): Matus Martini
Primary: Jesse Nusbaumer
Alternate(s): Courtney Peverley
Primary: Dustin Swales
Alternate(s): Michael Kavulich
Primary: Dan Rosen
Alternate(s): Ann Tsay
Primary: Steven Vahl
Alternate(s): François Hebert
The committee will be scheduled to meet biweekly, but meetings may be cancelled if there are no topics for discussion. All members listed as the primary contact for their group should plan to attend; if they can not attend a meeting they should attempt to get one or more alternates to attend in their place.
This is especially important when proposing changes to rules, or changes to/removal of existing names, as this requires broad approval from all interested groups.
Changes to standard names, rules, or other items in the ESMStandardNames repository should be handled via GitHub Pull Request. It is strongly encouraged to open issues describing proposed changes before a Pull Request is opened.
All proposals require at least two approvals before being accepted, and any member of the committee may reject proposed changes. See the section on “Guidance for code reviewers” for more details.
All development should be committed to the main branch outside of special cases (like release branches). When opening a PR, follow the instructions provided in the PR template.
A PR may be opened in “draft” mode if it is not ready for review; in this case, the PR title should have the literal text “DRAFT:” at the beginning. A draft PR will not be tested/reviewed until it is brought out of draft, although any member may offer comments at that stage, and a developer may request a review from a particular Github user if they add a comment to the PR using the Github notification method (e.g. @username).
It may occasionally be necessary to convert an open PR into draft, but if that is done the title must be edited with the “DRAFT:” text at the beginning, and a comment must be added to the PR notifying everyone that it has been turned into a draft PR. It will also be assumed that the review requirements will be reset for the PR, and won’t be restarted until the PR is brought out of draft again.
CI tests are set to run automatically once a PR is opened. These include ensuring that the standard names XML matches the metadata file, and that all standard names in the dictionary follow the existing rules. All tests must pass before a PR will be considered for merging. More testing may be rolled into continuous integration in the future as needed.
Simple changes can be merged after approvals from two reviewers, provided that the new names conform to all existing rules and all automated tests are passing. Examples of simple changes include the following.
- Introduction of new names
- Changes to long_names
- Addition of new tests
More substantial changes will need approval from one member of all represented parties before they are accepted and merged. Examples of changes that need explicit approval of all parties are as follows.
- The modification or removal of existing names
- Changing standard name rules
If you are assigned as a reviewer of a pull request, please review the code as soon as possible. If you feel that you do not have the time or expertise to review the PR, you may remove your name from the list of reviewers unless you are the last reviewer from your organization.
There are three modes of review on GitHub Pull Requests: Comment, Approve, and Request Changes. Comments may be provided by anyone at any time. Approvals may be offered by any members of the Standard Names committee listed above, but only one approving review from each group will be counted towards the total needed for merging. Any member may “Request Changes” to a PR, and a change may not be merged until that reviewer either offers an Approval or removes their original request for changes.
After a PR has received the required approvals, and there are no additional requested changes or failing tests, the PR author or a code manager should merge the PR to the main branch. If the PR author does not have permissions to merge the PR, the code manager should perform the merge as soon as all criteria are satisfied. Otherwise, the PR author (or other designated person if the author is unavailable) should merge the PR once all criteria are satisfied. If an approved and ready PR has not been merged after several days, the code manager may step in and perform the merge. If, for some reason, the PR author does not want the PR merged right away, it should be converted back to a draft; however, if any changes are made, the PR must be re-approved before merger.
Merges to main should be performed via the "Squash-and-Merge" method. This method keeps the commit history concise–with only one commit per pull request–allowing for an easy-to-navigate code history.
The person who merges the PR should manually close any linked issues that are resolved by that PR, if they are not closed automatically.
Because changes to the dictionary of names used by a project can be invasive, the ESM Standard Names project has adopted the use of versioning tags. The current version is 0.2.0.
Tags will be created via the git tag functionality of the repository; this will allow easy access for projects that desire to pin their names to a specific version. The tag number should also be noted in the header of standard_names.xml and the XML schema file, though these do not need to be updated with every commit, only when a new tag is proposed/created.
Projects making use of the ESM Standard Names dictionary may desire stable tags from time to time; e.g. for simplifying documentation for official code releases. Tags for simple changes may be created by any developer with write access, so long as they follow the standard naming convention “v#.#.#”, incrementally higher than the previous tag. Tags incrementing the first or second digit should be agreed upon by all groups at a regular meeting (or via other communication) In general, tags should be incremented based on the complexity/invasiveness of the changes, as follows:
- Simple changes (e.g. added standard names, added tests, description changes, wording changes in rules that do not change meaning): increment final digit (0.2.0 → 0.2.1); then
- Moderate changes (e.g. changed/removed standard names, minor rules changes or new rules that do not require extensive changes to existing names): increment second digit (1.0.0 → 1.1.0); then
- Major changes (e.g. major rules changes that affect a large number of existing names, incompatible formatting changes to XML file): increment first digit (1.2.1 → 2.0.0).
Note that subsequent digits should be reset to 0 when incrementing the first or second digit.
In addition to being tagged via git’s tag functionality, the tag number is contained in the top-level xml entry:
<standard_names name="Earth System Modeling Standard Name Library" version="1.0">