Projects and Subprojects

Choose the right level for project context and analytical work.

A project is a broad scientific or operational objective. It may include several scientists, controlled or partner-provided data, multiple analytical workstreams, and several products.

A subproject is an independently understandable and executable workstream. Examples include NWS climate acquisition, a Bayesian risk model, a spread simulation, genomics, or a dashboard.

The useful rule is approximately:

One analytically coherent workstream = one repository.

This is not the same as “one scientist = one repository.” A scientist may contribute to several subprojects, and a subproject may involve several scientists. Each subproject has one designated canonical working repository, even when forks, upstream repositories, or collaborator-owned repositories also exist.

Where information belongs

  • Project level: objective, scope, roles, decisions, milestones, controlled-data stewardship, subproject registry, and products.
  • Subproject level: scientific implementation, workflow entry points, public data acquisition, code, analytical provenance, and reproducibility notes.
  • Run level: exact configuration and execution records for a particular analysis or computational run.

Use the subproject README template and GeoEpi Version 1 .geoepi.yml template when setting up a repository. The metadata file is the current GeoEpi convention for reporting a small amount of portfolio-level state. It does not replace the README or run records.

Stable identifiers

project_id and subproject_id must be stable lowercase machine-readable identifiers. Use short but understandable, hyphen-separated ASCII names with no spaces. Both identifiers must match:

^[a-z0-9]+(?:-[a-z0-9]+)*$

Do not add dates unless a date is genuinely part of the scientific identity, and do not change an ID merely because a project title changes.

Repository names do not need to match an identifier and may retain the capitalization used by GitHub. This is valid:

project_id: hpai-plume
subproject_id: epiplume

repository:
  canonical: geoepi/EpiPlume

Do not rename a GitHub repository solely to make its capitalization match a stable ID.

Stable IDs connect Hub directory names, Hub registries, .geoepi.yml, GitHub Actions, and other machine-readable references where appropriate. GeoEpi does not prescribe a universal run ID convention.

Registry, metadata, and status

The Hub registry answers where is this subproject? The distinction is:

  • subprojects.yml = where the canonical subproject repository is located;
  • .geoepi.yml = current portfolio-level state reported by that subproject.

The registry locates the subproject; the subproject describes its state. Keep the registry minimal and do not duplicate lead, status, current focus, milestone, or compute fields there.

Version 1 of .geoepi.yml uses this small status vocabulary:

  • planned — work is defined but not underway;
  • active — work is underway;
  • paused — work is intentionally on hold;
  • complete — the current subproject objective is complete;
  • archived — the repository is retained for reference and is not active.

A Version 1 record uses the existing fields shown in the metadata template: schema version, stable IDs, title, summary, structured lead, status, current focus, repository information, optional compute locations, and an optional next milestone. Do not add local portfolio fields to this schema.

The file contains portfolio-level metadata only. It does not contain run records, package or environment versions, SLURM jobs, model parameters, seeds, detailed data provenance, analytical results, or validation output. Those remain in the subproject repository and/or computational environment.

Write the free-text fields concisely

current_focus

Use current_focus for a short description of what is happening now in the subproject. Prefer one concise phrase or sentence, for example:

Prospective validation.
Adding additional environmental variables.
Manuscript revision following reviewer comments.

Do not use it as a complete project history.

next_milestone.description

Use next_milestone.description for the next meaningful scientific, analytical, review, or delivery milestone. Describe a concrete next event or deliverable.

next_milestone.target

Use next_milestone.target for the expected date of that next milestone or review point. Use an ISO date such as 2026-09-01.

For complete and archived subprojects, next_milestone may be omitted. For a paused subproject, use it only when there is a meaningful review, restart, reassignment, or decision date. Do not use a historical publication or completion date as a future milestone. If historical completion dates need structured representation later, handle that in a future schema discussion rather than adding a Version 1 field.

See Add a Project or Subproject when registering work in the operational Hub.