17. Contributing

Contributing

Language: English. Chinese version: 17. Contributing (中文)

Trail Mate welcomes outside contribution, but the MCU feature set is frozen. Contributions should make this decentralized-phone-like terminal more reliable in anonymous operation, decentralization, offline operation, and TAK rather than expand its product surface.

Align On One Premise First

The project is still author-led. The README already makes clear that contributions involving core architecture or license changes are not automatically within the normal acceptance path. The closer a change gets to the project’s mainline boundaries, the more important it is to align on intent before making a large implementation change.

This is not about making contribution difficult. New major domains, a fourth product protocol, mandatory phone/cloud dependencies, or changes to position-authorization semantics are outside the contribution scope.

The Most Valuable Types Of Contribution

The highest-value contributions are not always code.

• real field feedback: hiking, camping, patrol, overlanding, or site-support feedback about what information is actually critical, what slows down decision-making, and what cannot be trusted under weak-link or low-power conditions
• device adaptation feedback: input issues, sleep differences, GPS behavior, radio limits, screen readability, and resource constraints on specific boards
• protocol interoperability feedback across Meshtastic, MeshCore, Reticulum/LXMF, and Trail Mate Team extensions; report external-host RNode/KISS issues explicitly as HostLink runtime cases
• troubleshooting material: high-quality logs, reproduction steps, SD-card directory examples, map resource failures, and serial traces
• documentation improvements: any change that reduces misunderstanding, lowers repeated support cost, or preserves design boundaries

What To Prepare Before Filing An Issue

When opening an issue, try to describe the whole path rather than only the final symptom. At minimum, it helps to include:

• the device and build target, such as tlora_pager_sx1262, tdeck, or gat562_mesh_evb_pro
• whether the firmware came from a release asset or local build
• the active protocol: Meshtastic, MeshCore, or Reticulum; for Reticulum, include a redacted SD config.json and the reported configuration source
• region or MC Region Preset, and whether TX Power, BW/SF/CR, channel, or key values were changed
• whether an SD card is inserted and what the approximate map directory layout looks like
• steps to reproduce, ideally in a repeatable way
• serial logs or key output from Trail Mate Center

If the problem is specifically about maps, Team, the desktop tool, or flashing, it also helps to mention whether you already checked the corresponding wiki page.

When It Is Better To Contact The Author First

The repository’s NOTICE and README already suggest that some subjects may be better handled outside a public issue thread, for example:

• commercial integration or preloaded firmware distribution
• deeper protocol analysis, hardware porting, or system-level evaluation
• logs, configurations, or deployment details that are not appropriate to publish publicly
• changes that touch core design boundaries and would be expensive to reverse

In those cases, direct contact can be more efficient than opening a vague public issue first.

Pull Request Boundaries

PRs are welcome, but Trail Mate is not a contest to accumulate features. The PRs that fit best usually have these characteristics:

• they strengthen anonymous operation, decentralization, offline operation, or TAK rather than generic feature expansion
• they distinguish protocol interoperability from project-specific extensions instead of mixing the two
• they do not assume every device should expose the same pages, input model, or feature set
• they respect constrained targets, especially devices like GAT562
• they update necessary documentation alongside the code

The following kinds of changes may be technically possible but are not automatically good fits:

• turning the project back into a generic LoRa feature pile
• adding a new major MCU product domain or fourth product protocol
• blurring public discovery, contact position, Team position, and local tracks
• making a phone, cloud, MQTT, or Center mandatory for core operation
• flattening hardware-specific differences just for visual uniformity
• describing unstable protocol paths as if they were already public guarantees
• heavily reshaping settings, map behavior, or Team semantics without a grounded use-case reason

A Good Pre-Submission Checklist

Before submitting, it helps to ask:

• what real problem does this change solve
• does it change user-visible behavior, and if so, was the documentation updated
• does it alter protocol interoperability boundaries, and if so, is that clearly explained
• does it affect constrained targets, and if so, was that impact checked
• does it make troubleshooting harder, and if so, were logs, error messages, or documentation improved

If you change map layout, track format, HostLink behavior, settings, board behavior, or Team data paths, update the related wiki page at the same time. Otherwise the support cost simply shifts to later users and maintainers.

Documentation Is A First-Class Contribution

Trail Mate’s wiki is not only a manual. It is also where design intent is preserved. That makes the following especially valuable:

• documenting known issues on a specific board
• clarifying a protocol boundary
• documenting common flashing or map-preparation mistakes
• explaining why something was designed this way

In this project, documentation that removes misunderstanding can be just as valuable as code.

Special Notes For Hardware Adaptation Contributions

If you are adapting a new board, try to work within the current repository direction:

• keep protocol, map, and UI business logic in reusable layers when possible
• keep board-specific differences inside boards/, variants/, platform adaptation, and capability gates
• define the device boundary clearly before deciding what to trim
• do not damage long-term structure just to get a board to boot quickly

In other words, the most important part of a new board adaptation is not only getting pixels on the screen. It is avoiding new maintenance debt.

License Reminder

Unless stated otherwise, code and content submitted to the repository should be understood as contributions under the project’s current license terms. The main repository currently uses AGPLv3, and COPYRIGHT also describes the separate commercial-licensing path.

If your organization or customer cannot accept that baseline, resolve the licensing question before submitting code rather than afterward.

Information Still Worth Adding

Two future collaboration improvements would be especially useful:

• a more explicit validation checklist, such as which minimum build targets should be tested for specific kinds of change
• issue and PR templates specialized for map problems, protocol problems, and hardware adaptation

The repository does not currently provide all of those templates yet, so the wiki serves as the main guidance for now.