DOI-USGS / DOI-USGS/dataretrieval-python

Apply term ownership to NLDI, NGWMN, and WQP prose

Đang mở
#408 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
ready-for-agent
Ngôn ngữ chính
Python
Star
266
Fork
63
Merge trung bình
1 ngày 20 giờ
Pull request đã merge (30 ngày)
19

Mô tả

## Parent

#406

## Ownership rule

ADR 0013 separates package-owned core vocabulary from service-owned domain vocabulary:

- `getter` is a dataretrieval core term. It applies only to public functions returning `(DataFrame, metadata)` and binds package prose and tests.
- `collection` is a domain concept. Adapter prose should accurately translate the service's own vocabulary, while public parameters and wire spellings remain native to that service.

Primary sources settle the three adapters differently:

- [NLDI's official documentation](https://api.water.usgs.gov/docs/nldi/) calls its operations **navigation functions**. The Python adapter returns GeoDataFrames or JSON directly, without a metadata tuple, so calling these functions getters is a package vocabulary defect.
- [NGWMN's live OGC collections document](https://api.waterdata.usgs.gov/ngwmn/ogcapi/collections) publishes `sites`, `providers`, `waterLevelObs`, and the other record sets as **collections**. Prose calling those collection identifiers services is upstream-inaccurate; NGWMN itself remains the service.
- [WQP's official Web Services Guide](https://www.waterqualitydata.us/webservices_documentation/) calls these endpoints the **Station Web Service**, **Result Service**, and **profile services**. `dataProfile` is a separate request parameter. WQP's public `service` vocabulary is therefore native domain language and must not be normalized away.

## What to build

Apply those ownership decisions consistently without changing public behavior:

1. Describe NLDI's direct-return operations as navigation functions rather than getters, including package and test prose.
2. Describe NGWMN OGC collection identifiers as collections in prose and comments, while continuing to call the external NGWMN system a service.
3. Correct the shared glossary so it distinguishes WQP's Result/Station/Activity services from the separate `dataProfile` values.
4. Preserve WQP's public `service` parameters, URL-builder documentation, exported names, wire paths, and other service-oriented public prose.

## Acceptance criteria

- [ ] NLDI prose and test comments no longer call direct GeoDataFrame or dictionary-returning functions getters.
- [ ] NLDI is described as navigation functions, matching both its return contract and official API documentation.
- [ ] NGWMN prose and comments use collection for identifiers exposed by its OGC `/collections` document.
- [ ] References to the external NGWMN system continue to use service.
- [ ] The glossary accurately records that WQP exposes Result, Station, and Activity services and treats `dataProfile` as a separate concept.
- [ ] WQP's public `service` terminology and service-oriented URL-builder documentation remain unchanged.
- [ ] Deprecated NWIS vocabulary, Samples resource/code-service terms, the deprecated CQL keyword, and permanent aliases remain unchanged.
- [ ] No public name, signature, return shape, exported value, wire parameter, URL, or runtime behavior changes.
- [ ] Documentation, offline adapter tests, lint, and architecture checks pass.

## Blocked by

None — can start immediately.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Bắt đầu với ADR 0013 và tài liệu chính thức về NLDI, NGWMN và WQP được liên kết trong issue. Tìm các thuật ngữ bị ảnh hưởng trong phần mô tả của adapter, các chú thích trong test và glossary dùng chung, sau đó chạy các offline adapter tests, lint và architecture checks. Được xem là hoàn tất khi các thay đổi về thuật ngữ khớp với từng service, trong khi public names, parameters, URLs, return shapes và runtime behavior vẫn không thay đổi.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
python
Lĩnh vực
documentation
Loại issue
Tài liệu
Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức độ hoạt động
Sôi nổi
Độ rõ ràng
Đặc tả rõ ràng
Mức phù hợp với người mới
68/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.