Skip to content

docs: use the glossary's terms for collections and locations - #402

Merged
thodson-usgs merged 1 commit into
DOI-USGS:mainfrom
thodson-usgs:chore/glossary-terms
Sep 2, 2026
Merged

docs: use the glossary's terms for collections and locations#402
thodson-usgs merged 1 commit into
DOI-USGS:mainfrom
thodson-usgs:chore/glossary-terms

Conversation

@thodson-usgs

@thodson-usgs thodson-usgs commented Sep 1, 2026

Copy link
Copy Markdown
Collaborator

Why

A glossary pass over the package, scoped to the modules that are not
deprecated. Prose says collection where it meant one of a service's named
sets of records, and monitoring location where it meant a place measurements
are recorded.

Parameters are untouched throughout. site_type=, site_type_code= and the
sites_df example variable are the services' own vocabulary and stay as they
are — that is the anti-corruption boundary working, not drift.

What changed

  • waterdata/measurements, metadata, ratings, samples,
    time_series: docstring prose and example comments.
  • ogc/planning.py — shared OGC machinery serves both Water Data and NGWMN, so
    nothing in it is about one service's spelling.
  • wqp.py_query_wqp's docstring and the module todo. WQP's profiles
    (Result, Station, Activity) are collections; the reference to
    services_wqx3 now notes that the name itself is legacy.
  • CONTEXT.md — one Known legacy names bullet, below.

Legacy NWIS is deliberately excluded

service= on the NWIS getters does name a collection. It is also frozen public
surface on a module being retired, so the parameter keeps its name and its
docstrings keep the same word
— describing a parameter in a term the module
itself never uses helps nobody, and the module is not where new vocabulary
should be landing. The CONTEXT.md bullet records that scope.

NEWS.md is left alone for the same reason. The two entries this originally
touched are both about deprecated NWIS, and shipped release notes are a
historical record rather than prose to bring into line.

Prose only

No executable code changed, verified by comparing the AST of every touched
module against upstream/main with docstrings stripped:

7 .py files changed; executable code differs in: NONE

1139 tests pass, ruff format --check clean.

Deferred, with a home

  • wqp.services_wqx3 / wqp.services_legacy hold collection names and are
    public. Tracked in Glossary violations across the package: full inventory for planning #406 §3 — it needs an ADR 0012 deprecation cycle, not a
    prose PR.
  • The censoredpartly dated wording in nwis.py, its tests, and the
    08/27 NEWS entry. A genuine terminology problem (in water data a censored
    value is one outside a detection limit — a meaning this package ships in
    wqp.what_detection_limits), but it is confined to deprecated NWIS and its
    release notes, so it is out of scope here. Worth its own small PR if wanted.
  • The pandas UserWarning raised in the first draft of this PR is fixed in
    fix(nwis): name the peak date format instead of making pandas guess #403.

Relationship to the other open PRs

Based directly on main. Touches no file #396 or #400 touches except
CONTEXT.md.

#405 overlaps here. It restructures Known legacy names and, under ADR
0013, moves domain terms at an adapter's surface out of that section and into
the term's own entry — where NWIS's service= is already named. Whichever
merges second should fold this bullet into the Collection entry rather than
keep both.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JAEQqs7XzQHGQQi2KakuXD

@thodson-usgs
thodson-usgs force-pushed the chore/glossary-terms branch 2 times, most recently from 2a6b32d to a6b8e99 Compare September 1, 2026 21:32
@thodson-usgs thodson-usgs changed the title docs: use the glossary's terms for collections, locations, and partial dates docs: use the glossary's terms for collections and locations Sep 1, 2026
Prose in the non-deprecated modules now says *collection* where it meant
one of a service's named sets of records, and *monitoring location*
where it meant a place measurements are recorded. The parameters are
untouched -- `site_type=`, `site_type_code=` and `sites_df` are the
services' own vocabulary and stay as they are.

Legacy NWIS is deliberately excluded. Its `service=` parameter names a
collection, but it is frozen public surface on a module being retired,
and its docstrings keep that word rather than describing a parameter in
a term the module itself never uses. `CONTEXT.md` records the carve-out.
NEWS entries are left alone for the same reason: both of the ones this
touched are about deprecated NWIS, and shipped release notes are a
historical record rather than prose to bring into line.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JAEQqs7XzQHGQQi2KakuXD
@thodson-usgs
thodson-usgs merged commit 9322ab0 into DOI-USGS:main Sep 2, 2026
11 checks passed
@thodson-usgs
thodson-usgs deleted the chore/glossary-terms branch September 2, 2026 01:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant