Skip to content

Write CONTRIBUTING.md 'Adding a new vendor' guide #4

Description

@bryanwintermute

Summary

receipt_print.py is brand-agnostic, but every NV-config CLI in the repo today is Rongta-specific (nv_config.py, ethernet_config.py, papersave_config.py, blackmark_config.py, other1_config.py, plus the rongta_config.py dispatcher). If a contributor shows up wanting to add Star / Bixolon / Xprinter / Epson NV-config support, there's no documented path for what to do or where files should land.

Proposal

Add a new section to CONTRIBUTING.md: "Adding a new vendor".

It should cover, end-to-end, what we did for Rongta so a contributor can follow it on their own printer without re-deriving the workflow:

  1. The capture rig pattern — Wine + a custom logging CUPS backend + USB-IP-export from a Pi. Link to docs/wine-cups-backend-recovers-nv-bytes.md which already has the recipe.
  2. The 4-clicks diffing methodology — all-off / only-X / only-Y / only-Z gives complete bit-mapping for any group of boolean NV flags.
  3. Where to put the new files. For now: top-level, prefixed with the vendor name (e.g., star_config.py). Note that a vendors/<name>/ layout is on the roadmap (#N, vendor-namespace-refactor) — if that lands first, new vendors go under vendors/<name>/.
  4. What tests look like — the dry-run byte-equality fixtures in tests/. We want the same contract for every vendor: emitted bytes are stable across refactors.
  5. PR template / labels — a vendor:<name> label per new vendor; what to include in the PR description (printer model, USB id, vendor-tool version captured against).
  6. Out-of-scope guardrails — sanitize / markdown / receipt-rendering work belongs in receipt_print.py, not in any vendor module. The vendor modules are only for NV-config and any other proprietary side-channels.

Doubles as an anchor

The README "Help wanted" block (WiFi tab, Bluetooth tab, UDP discovery, factory-reset checksum reversal, Voiceless-volume verification, cutter-stats BULK-IN response, etc.) currently links to a single help-wanted issue template. Once this guide exists, those help-wanted items can link to specific sections of it.

Acceptance

  • New section in CONTRIBUTING.md, ~150-300 lines.
  • README's "Help wanted" callout updated to link to the new section.
  • (Optional, if natural while writing): a per-new-vendor issue template at .github/ISSUE_TEMPLATE/.

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationhelp wantedExtra attention is needed

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions