Feat: Centralized maintainer ownership for CLI help and docs

[krowvin]

Fishing for thoughts on this: Do it, part of it, none of it, tweak it?

Long-term I think we want to consider one or more DLL or mailing lists for this to help with turnover. Could even use CDA to query for a group of emails over a specific command.

Adds a centralized maintainer/ownership workflow for cwms-cli uses it to surface maintainers in both the CLI help output and the docs.

This adds a user-friendly contact path for issue reporting. It is optional where ownership is not yet defined, and is intended to encourage users to report issues. Issues should always be created for feature requests, bugs, etc. Having authors on sub commands helps provide this contact path where making an issue might otherwise go unreported. Having some email to report something would enable maintainers to create followup issues.

(Issues do report a link to the github issues page for cwms-cli!)

What this does

This introduces a single ownership source of truth in cwms-cli/maintainers.toml.

From that file, the repo now generates and maintains:

• cwms-cli/.github/CODEOWNERS for GitHub review/accountability
• Poetry authors in cwms-cli/pyproject.toml
• runtime ownership metadata in cwms-cli/cwmscli/_generated/ownership_data.py
• docs include fragments under cwms-cli/docs/_generated/maintainers

That generated data is then used in two user-facing places:

• CLI help output shows Maintainers: on help pages

Each command has author(s) associated

• docs pages now show a maintainer note sourced from the same ownership file

Implementation details

The sync flow is handled by cwms-cli/scripts/sync_ownership.py

Current command ownership mapping:

• Charles: csv2cwms, blob, update, shared cwms-cli, shared load
• Eric: usgs, shefcritimport, shared cwms-cli, shared load

CLI help rendering was extended in cwms-cli/cwmscli/utils/click_help.py to show maintainers centrally, without hand-editing each command. Ownership lookup is handled by cwms-cli/cwmscli/ownership.py, and nested commands inherit from the nearest owned parent command.

Docs were updated to include generated maintainer blocks on the
current command pages:

• docs/cli.rst
• docs/cli/blob.rst
• docs/cli/csv2cwms.rst
• docs/cli/update.rst
• docs/cli/load_location_ids_all.rst

Contributing / maintenance

cwms-cli/CONTRIBUTING.md was updated to document the new workflow.

Contributors now have explicit guidance to:

• treat maintainers.toml file to maintain contributors in
• run python scripts/sync_ownership.py after ownership edits
• use python scripts/sync_ownership.py --check to verify generated files

There is also enforcement in both local hooks and CI:

• pre-commit now runs a generated ownership files check (Debatable if we need this?)
• GitHub Actions verifies generated ownership files are in sync (This is probably enough to make sure it is not forgotten)

Benefits

This gives cwms-cli a clear ownership model with one place to maintain it.

Benefits:

• maintainers are visible to users in CLI help and docs
• ownership and package author metadata stay aligned
• GitHub review routing now has an explicit CODEOWNERS base
• command ownership is easier to update during turnover
• changes to ownership are reviewable as normal repo diffs
• the same ownership data can be extended later without adding more manual duplication

Alternatives considered

Git history / recent commits

This was considered but not used as the primary maintainer source.

Reason:

• recent commits do not reliably indicate who is responsible
• contributors may touch files without becoming maintainers (Intentionally Opt-In) to maintaining
• ownership should survive turnover, refactors, and one-off fixes
• git activity is useful as a signal, but weak as a published accountability source

Manual per-command metadata in source files

This was also considered and partially existed already via author in csv2cwms.

Reason not chosen:

• duplicates data across multiple surfaces
• does not scale well across docs, package metadata, and GitHub ownership
• becomes harder to maintain consistently over time

CI-only generation

Not chosen.

Reason:

• CODEOWNERS must exist in the repository for GitHub to use it
• committed generated files give deterministic repo state and visible diffs
• CI is better used to verify sync, not to be the only place generation happens

Verification

Verified locally with:

• python scripts\sync_ownership.py
• python scripts\sync_ownership.py --check
• poetry run python -m pytest tests\cli\test_all_commands_help.py tests\cli\test_update_command.py -q
• python -m sphinx -nW -b html docs docs_build\html

Follow-up

This covers pages that already exist. For some of the sub commands they do not all have dedicated docs yet.