Quick Links¶

For Submitters¶

For Reviewers¶

Reviewer Labels¶

Review Procedure¶

Reviewing oldest first is a requirement — it ensures submitters are not left waiting indefinitely.

1. A pull request is created automatically when a submitter completes a form. Reviewers may be auto-assigned.
2. Open the PR and read the automated summary report posted as a comment. Then examine the JSON diff.
3. Approve the PR if the submission is scientifically valid, or request changes with clear, actionable comments.
   • All comments must be made using GitHub's Review mode on the pull request — not in the issue or elsewhere.
   • Suggestions that require the submitter to edit their entry should be left as comments on the original issue, not the PR, so the submitter sees them clearly.
4. On approval, a second reviewer or maintainer performs a sanity check and merges.

General Rules¶

These apply to all submissions and should be checked during review.

IDs and naming

• IDs must not contain underscores or spaces.
• Any periods . must be replaced with hyphens -. This applies to source IDs, model family names, and component version strings.
• Confirm this for every identifier in the submitted record.

Links and references

• All links must point to permanent locations: version control platforms (GitHub, GitLab, Bitbucket) or DOIs.
• If a submitter needs a DOI for an otherwise unpublished resource, Zenodo can mint one for free.

Grid descriptions

• A description field on a grid record should only exist to document a difference between two otherwise identical parameter sets that cannot be captured by any structured field.
• Do not accept descriptions that simply restate the grid type or parameters already present in other fields.

How to Read an EMD Report¶

Every pull request includes an automated summary report as a comment. This is your primary review tool — read it before examining the raw diff.

Check the overall structure first. Ensure all required sections are present and populated. Compare against the latest EMD specification.

Review validation outputs. Errors indicate mandatory issues that must be fixed before merging. Warnings highlight potential inconsistencies or missing best practice — use your judgement on whether they need addressing.

Inspect identifiers and references. Confirm IDs follow the naming rules above. Ensure any referenced entities (grids, component configs, families) already exist in the registry and are correctly linked.

Assess the semantic content. Check that descriptions are meaningful and not duplicated unnecessarily. Ensure fields are used as intended — for example, grid description fields should not be used to encode information that belongs in a structured field.

Follow all links. Verify that references resolve and point to stable, permanent resources. A link to a personal Dropbox or an unversioned URL should be flagged.

The goal is not only to confirm technical validity, but to ensure the submission is clear and usable by others.

Grid Similarity¶

Duplicate or near-duplicate grid submissions are a common review concern. Before approving any grid record:

• Check whether a similar or identical grid already exists in the registry. The automated duplicate-detection comment on the PR is a starting point, but it is not exhaustive — apply your own judgement.
• Minor differences in naming or description do not justify a new record. A new grid entry is warranted only when there are structural differences (resolution, topology, cell count, indexing) or when the physical interpretation differs in a way that cannot be captured by existing fields.
• If you are unsure, tag the PR with needs checking and request input from a domain expert rather than approving or rejecting outright.

Requesting Changes¶

When requesting changes, provide clear and pasteable guidance so the submitter knows exactly what to do. Always include:

• What needs to change and why
• Where to make the change (field name, section)
• How to rerun the action after editing (link to the Scribe guide if helpful)

Leave change requests as comments on the original issue, not the PR. This ensures the submitter's notification goes to the right place, and the edit-to-update loop works correctly — when the submitter edits the issue body, the PR updates automatically.

Reviewer Project Board¶

The project board provides a consolidated view of all active submissions. It contains:

• Open submissions awaiting review
• Submissions with pull requests under active review
• Non-form issues (general discussions and questions)
• A tab per form group to make it easy to filter by record type

Columns are managed via issue labels. After an approval, an automated action removes the needs-review label and the PR moves to the approved column. Approved PRs are shown with a green tick on the pull requests page.

How to Submit a Review on GitHub¶

Changes and Corrections¶

The full link to guidance on comments and template code is provided in here. The current guidance is to submit a formal review (see image below), whereupon completion any suggested changes will be copied to the issue as well.

Listing Pull Requests from the Command Line¶

A helper script is available on the main branch for reviewers who prefer the terminal:

git checkout main && .github/pr_issue_map.sh

Example output:

PR #86 [OPEN] — New Horizontal_computational_grid : g108-mass | tempgrid_wolfiex-1774629370
  [+] Approved : -
  [~] Engaged  : -
  └─ Issue #80 [OPEN] — New Horizontal_computational_grid : g108-mass, tempgrid_wolfiex-1774629370

PR #78 [OPEN] — New Vertical_computational_grid : tempgrid_wolfiex-1774628619
  [+] Approved : -
  [~] Engaged  : davidhassell
  └─ Issue #77 [OPEN] — New Vertical_computational_grid : tempgrid_wolfiex-1774628619

Filter flags: --approved, --needs-review, --json (for structured output).

Using Copilot as a Third Reviewer¶

Copilot may be added as a reviewer only after you have completed your own manual review.

It must not be used as a primary reviewer and is still in training — it can and does produce incorrect results.

Appropriate uses:

• Sanity checking your own conclusions
• Flagging weaknesses you may have missed
• Suggesting grammar or phrasing improvements in description fields
• Identifying potential duplication

When working with Copilot suggestions:

• Never use "Fix all" or "Apply all fixes"
• Manually review each suggestion before acting on it
• Resolve and dismiss conversations that are not relevant
• Do not ask Copilot to review subgrid records — these are auto-generated