Skip to content

docs/chore: audit OpenGD77/1701 import-export implementation against reference docs #91

Description

@pskillen

Problem

The import/export documentation was collated and restructured under docs/features/import-export/ (#84), and the authoritative wire-format reference lives under docs/reference/opengd77/ (#43).

The docs describe the intended behaviour, but the shipped OpenGD77/Baofeng 1701 import and export code has not been systematically audited against them since the restructure. Where docs and code disagree, code wins until fixed (per the reference hub) — but we should confirm they actually agree, and ticket any gaps.

This item is carried as open debt in docs/features/import-export/outstanding.md.

Intended outcome

A documentation/accuracy audit (not a feature). Walk every documented behaviour against the implementation and either confirm alignment or file follow-up issues for code/doc gaps.

Scope — confirm code matches docs

  • Per-column mapping — every column in docs/reference/opengd77/ (channels, zones, contacts, tg-lists, dtmf-aprs) matches src/lib/import/opengd77/parse.ts + columns.ts and src/lib/export/opengd77/serialise.ts.
  • Conversion rules — booleans (Yes/No), VOX (Off/On), ID TypeTalkGroup/Contact, name-based FK denormalisation.
  • ClassificationdetectKind heuristics in opengd77/README.md match adapter.ts.
  • Skip vs errorDTMF.csv/APRS.csv skipped on import; header-only on export; parse-failure vs skip behaviour.
  • Cardinality — 1701 profile constants (80 zone members, 32 TG list members) match hard-coded export padding/truncation.
  • Lossy fieldsvendorExtras round-trip, app-only fields (hideFromMap), header-only files behave as documented.
  • Merge semantics — match keys, idempotent re-import, zone member re-resolution match hub README and importMerge.ts.

Method

  1. Read each reference/adapter doc; tick or flag each documented behaviour against code.
  2. Cross-check existing tests (parse.test.ts, roundtrip.test.ts, importMerge.test.ts, system suite) cover the documented behaviour; note coverage gaps.
  3. For each discrepancy: fix the doc if the code is correct, or file a code-bug follow-up issue (code wins until fixed).
  4. Tick the audit item in outstanding.md when complete.

Affected

  • docs/reference/opengd77/*.md, docs/features/import-export/**
  • src/lib/import/opengd77/, src/lib/export/opengd77/
  • Possibly new follow-up issues for code gaps

Out of scope

  • Implementing the radio profile picker (#72).
  • Modelling APRS/DTMF (tracked in outstanding.md).
  • New vendor formats.

Notes

  • Follow-up to #84; discovered-debt item in outstanding.md.
  • Docs-only unless the audit surfaces code bugs worth ticketing separately.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions