rich/MeshTerm
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Say how the project is run, and ask better bug questions

Browse Source 
The bug form now asks what JP's Discord post asks: how often it happens, whether
there's a workaround, what hardware you're on, and which companion device — with
the note that "a Xiao" doesn't narrow anything down. Three things his post didn't
cover got added: the MeshTerm version, whether it still happens under `--mock`
(which splits an app bug from a radio bug before anyone spends an evening on it),
and whether you're on the regular or PicoCalc look, since those draw differently
enough that a bug in one often doesn't exist in the other.

The README gains the part that was missing: what to expect from a maintainer
doing this on evenings and weekends. Issues welcome, ask before opening a pull
request, no promised timelines, and a nudge on a quiet issue is fine. Report on
GitHub or on Discord, whichever you have — the real ones get moved across either
way, and being told beats filing it tidily.

Install is rewritten for someone who wants to run MeshTerm rather than work on
it. It said `pip install -e ".[dev]"`, which is a contributor's command and puts
pytest and ruff on the machine of somebody who just wants to talk to a radio. Now
it's one pip line, a pipx alternative, `--mock` for people without a radio yet,
and an honest "coming" list for installers and PyPI.

Badges now include CI, the licence and Discord, so they say something checkable
rather than only decorating. The two survey documents get a line at the top
saying they're a snapshot of a date, not a to-do list.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5 committed 2026-09-07 04:56:51 -04:00
1 parent 628b665420
commit ab8ef2aa23
6 files changed
+200 -53
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.github/ISSUE_TEMPLATE/bug.yml
+113 -40
View File
@@ -1,28 +1,47 @@
name: Bug report
description: Something MeshTerm does wrong, and how to see it happen
description: Report a problem with MeshTerm
labels: [bug]
body:
- type: markdown
attributes:
value: |
The fields below are the ones that get asked in every single bug thread, so
answering them up front usually saves a day of back-and-forth.
Hopefully you never need this form.
If you do: how much of this you fill in really does decide what happens next. A
report I can act on gets worked on. A vague one usually doesn't, because I can't
do anything with it. If it isn't worth describing properly, it's probably not
worth fixing.
Most of these take ten seconds each.
- type: textarea
id: what-happened
id: problem
attributes:
label: What happened
description: What you saw, and what you expected instead.
label: What's the problem
description: What happens, and what you expected to happen instead.
validations:
required: true
- type: dropdown
id: how-often
attributes:
label: How often does it happen
options:
- Every single time
- Often, but not always
- Now and then, no pattern I can see
- Once, and I haven't seen it since
validations:
required: true
- type: textarea
id: repro
attributes:
label: How to see it happen
label: How do I make it happen
description: >
The screens and keys, in order. "Contacts, Enter on a node, Routes tab, Enter on
the second route" beats "open a trace".
The steps, in order, starting from launching MeshTerm. Screens and keys beat
descriptions — "Contacts, Enter on a node, Routes tab, Enter on the second route"
is worth more than "open a trace".
placeholder: |
1.
2.
@@ -30,70 +49,124 @@ body:
validations:
required: true
- type: textarea
id: workaround
attributes:
label: Is there a way around it
description: Anything that avoids it, or gets you unstuck. Say so even if it's ugly.
- type: input
id: version
attributes:
label: MeshTerm version
description: Shown on the splash screen and on the About page.
description: It's on the splash screen when you start, and on the About page.
placeholder: "0.2.0"
validations:
required: true
- type: dropdown
id: platform
- type: input
id: hardware
attributes:
label: Which flavour
label: What are you running MeshTerm on
description: >
MeshTerm draws itself differently on a PicoCalc — 53 columns, sixteen colours, a
different font. A bug in one flavour often does not exist in the other.
options:
- Regular (desktop or ssh)
- PicoCalc
validations:
required: true
- type: dropdown
id: transport
attributes:
label: How the companion is connected
options:
- USB / serial
- Bluetooth
- TCP
- No companion (simulator / --mock)
Desktop, laptop, Mac, or a handheld — and if it's a handheld, which one.
placeholder: "ClockworkPi uConsole (CM4), or: desktop PC"
validations:
required: true
- type: input
id: os
attributes:
label: Operating system and Python version
placeholder: "Windows 11, Python 3.12"
label: Which OS, exact version
placeholder: "Windows 11 24H2 / macOS 15.3 / Debian 12"
validations:
required: true
- type: input
id: terminal
attributes:
label: Terminal, and its size in columns x rows
label: Which terminal, and how big
description: >
Layout bugs are usually terminal bugs. Which terminal, and how big, decides
whether anyone can reproduce what you are seeing.
PowerShell, Windows Terminal, iTerm2, the PicoCalc console, ssh from something.
Size in columns x rows if you know it — a lot of layout bugs are really terminal
bugs.
placeholder: "Windows Terminal, 120x40"
validations:
required: true
- type: input
id: companion
attributes:
label: Which companion device
description: >
Be precise. There are a lot of these and they don't behave the same. "A Xiao"
doesn't narrow it down — "Seeed XIAO nRF52840 + Wio-SX1262" does. Leave blank if
no radio was involved.
placeholder: "Heltec V3 / RAK4631 / XIAO nRF52840 + Wio-SX1262"
- type: input
id: firmware
attributes:
label: Companion device and firmware version
description: Leave blank if no radio was involved.
placeholder: "Heltec V3, MeshCore 1.15.0"
label: Which firmware version is on it
placeholder: "MeshCore 1.15.0"
- type: dropdown
id: transport
attributes:
label: How is it connected
options:
- USB / serial
- Bluetooth
- TCP
- SPI-to-TCP bridge
- Something else (say so below)
- No radio — simulator / --mock
validations:
required: true
- type: dropdown
id: flavour
attributes:
label: Regular or PicoCalc
description: >
MeshTerm draws itself differently on a PicoCalc — narrower, fewer colours, a
different font. A bug in one often doesn't exist in the other, so this saves a
round of guessing.
options:
- Regular (desktop, laptop, ssh)
- PicoCalc handheld
- Not sure
validations:
required: true
- type: dropdown
id: mock
attributes:
label: Does it still happen with `meshterm --mock`
description: >
`--mock` runs the whole app against a fake radio. If the bug survives that, it's
in MeshTerm and I can chase it without hardware. If it doesn't, it's in the link
or the radio, which is a different hunt. Skip it if the bug is about connecting
in the first place.
options:
- "Yes, still happens with --mock"
- "No, --mock is fine"
- "Haven't tried"
- "Doesn't apply"
- type: textarea
id: error
attributes:
label: The exact error, if there was one
description: >
Copy it as text rather than photographing the screen — text can be searched, and
a photo of a terminal is hard to read. Paste the whole traceback if it crashed.
render: text
- type: textarea
id: extra
attributes:
label: Anything else
description: >
A screenshot of the screen, the traceback if it crashed, or what the radio was
doing at the time. Paste text rather than a photo of text where you can.
Did it used to work? Did it start after an update? Screenshots of a wrong-looking
screen are genuinely useful here, even though text is better for errors.
.github/ISSUE_TEMPLATE/config.yml
+9 -3
View File
@@ -1,7 +1,13 @@
blank_issues_enabled: false
contact_links:
- name: Questions, setup help, and general mesh chat
- name: Not sure it's a bug? Ask on Discord
url: https://discord.gg/AZwe5Uvb3S
about: >
Not sure whether it's a bug? Ask on Discord first — it's faster, and someone
running the same radio has probably hit it.
Setup trouble, "is it supposed to do this", or anything you want a second opinion
on. The support forum is the place. Someone running your radio has probably hit it.
- name: No GitHub account? Report it on Discord instead
url: https://discord.gg/AZwe5Uvb3S
about: >
Drop reproducible bugs in #bugs and they'll get moved here. Being told beats
filing it tidily.
.github/ISSUE_TEMPLATE/feature.yml
+1 -1
View File
@@ -1,5 +1,5 @@
name: Feature request
description: Something MeshTerm should be able to do
description: Suggest a feature or an improvement
labels: [enhancement]
body:
- type: markdown
README.md
+67 -9
View File
@@ -14,11 +14,17 @@ radio overhears is recorded to a local SQLite database, so the longer you run it
your mesh's history is worth.
<p>
<a href="https://github.com/jpmartineau/MeshTerm/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/jpmartineau/MeshTerm/actions/workflows/ci.yml/badge.svg"></a>
<img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue">
<a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-green"></a>
<img alt="For MeshCore" src="https://img.shields.io/badge/for-MeshCore-8A2BE2">
<img alt="Interface: TUI + CLI" src="https://img.shields.io/badge/interface-TUI%20%2B%20CLI-orange">
<a href="https://discord.gg/AZwe5Uvb3S"><img alt="Discord" src="https://img.shields.io/badge/chat-Discord-5865F2"></a>
</p>
> MeshTerm is a side project, not a product. Bug reports are very welcome — but please
> open an issue before writing a pull request. [More on how it's run](#how-this-project-is-run).
<!--
Screenshots welcome here. Drop PNGs into docs/ and reference them, e.g.:
![Dashboard](docs/dashboard.png)
@@ -48,19 +54,36 @@ your mesh's history is worth.
## Install
```bash
git clone <your-fork-url> meshterm
cd meshterm
pip install -e ".[dev]"
```
Python **3.10+** is required (matching the `meshcore` library). The `[dev]` extra adds
pytest and ruff; drop it for a runtime-only install (`pip install -e .`).
You need **Python 3.10 or newer**. That's the only requirement — MeshTerm pulls in
everything else itself.
```bash
python -m pytest -q # run the test suite
pip install git+https://github.com/jpmartineau/MeshTerm
meshterm
```
`meshterm` opens the full-screen menu. That's the whole install.
**Rather not touch your system Python?** [pipx](https://pipx.pypa.io/) puts the app in its
own private environment and still gives you a plain `meshterm` command:
```bash
pipx install git+https://github.com/jpmartineau/MeshTerm
```
**No radio yet?** `meshterm --mock` runs the entire app against a simulated mesh, so you
can have a look around before you buy anything.
### Coming
- **Downloadable installers** for Windows, macOS and Linux, so you won't need Python at
all. They'll show up on the [Releases](https://github.com/jpmartineau/MeshTerm/releases)
page.
- **`pip install mesh-term`**, once the package is published. It isn't yet — the name
question is still being sorted out ([why](https://github.com/pypi/support/issues/12162)).
Setting up for development instead? That's in [CONTRIBUTING.md](CONTRIBUTING.md).
## Quick start
```bash
@@ -253,6 +276,41 @@ Adding a feature means subclassing `Tool`, decorating it with `@register`, and
implementing `run()`. The same registry builds both the CLI and the menu, and the base
class wraps every execution in a logged `runs` row automatically.
## How this project is run
MeshTerm is one person working evenings and weekends. I'd rather tell you that up front
than have you guess from how long things take.
**Issues are welcome — all of them.** Bugs, questions, "is this supposed to do that". The
[bug form](.github/ISSUE_TEMPLATE/bug.yml) asks for a fair bit, and that's on purpose: how
well a problem is described really does decide whether I can do anything with it. If I can
reproduce it, I'll usually chase it. If I can't, I'm mostly guessing.
**Ask before you write a pull request.** Open an issue first and wait for a yes. I'm not
being precious — MeshTerm has firm house rules about how screens get built (they're in
[CLAUDE.md](CLAUDE.md)), and I'd hate for you to spend a weekend on something I then ask
you to rewrite. A quick conversation first saves us both.
**I can't promise timelines.** Some things get fixed the same night. Some sit for a month
because life happened. If your issue goes quiet, a nudge is completely fine — it's not
rude, it's helpful.
**Where to report things.** Either works:
- **[GitHub issues](https://github.com/jpmartineau/MeshTerm/issues)** if you have an
account. This is where things get tracked and fixed, so it's the shortest path.
- **[Discord](https://discord.gg/AZwe5Uvb3S)** if you don't, or if you're not sure it's a
bug yet. Ask in the support forum, or drop reproducible defects in `#bugs`. I move the
real ones over to GitHub myself.
Don't worry about picking the wrong one. Getting told about a problem beats filing it
tidily.
Also here: [CONTRIBUTING.md](CONTRIBUTING.md) ·
[SECURITY.md](SECURITY.md) ·
[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) ·
[CHANGELOG.md](CHANGELOG.md)
## Development
```bash
docs/survey-navigation.md
+5
View File
@@ -1,5 +1,10 @@
# Navigation survey — every exception to "Esc pops the stack"
> **A historical record.** This was a snapshot of the code on the date below, kept
> because a project that writes down its own problems is easier to trust than one
> that doesn't. Some of what's here has since been fixed and some hasn't; nothing in
> it is a to-do list. Read it as "what this looked like then", not "what is wrong now".
Written 2026-08-22 against `main` @ `4b29248`. A catalogue, not a change: nothing here had
been fixed at the time of writing. Each finding says where it is, what it does, and what
makes it a question.
docs/survey-ui-consistency.md
+5
View File
@@ -1,5 +1,10 @@
# UI consistency survey — what is off, and what turned out to be fine
> **A historical record.** This was a snapshot of the code on the date below, kept
> because a project that writes down its own problems is easier to trust than one
> that doesn't. Some of what's here has since been fixed and some hasn't; nothing in
> it is a to-do list. Read it as "what this looked like then", not "what is wrong now".
Written 2026-08-22 against `main` @ `4b29248`. Companion to
[`survey-navigation.md`](survey-navigation.md), which covers navigation exceptions; this one
covers everything else in the CLAUDE.md UX standard. A catalogue, not a change.