From 1f7ded8f3fc5a50b322fb605d7b22c3af751b6fd Mon Sep 17 00:00:00 2001 From: Ben Allfree Date: Tue, 6 Oct 2026 22:25:02 -0700 Subject: [PATCH] docs(repo): plugin layout and release tagging --- .cursor/rules/commit-message-convention.mdc | 10 ++--- .cursor/rules/lobbs-project.mdc | 15 +++---- .cursor/rules/release.mdc | 46 +++++++++++++++++++++ README.md | 38 ++++++++--------- 4 files changed, 78 insertions(+), 31 deletions(-) create mode 100644 .cursor/rules/release.mdc diff --git a/.cursor/rules/commit-message-convention.mdc b/.cursor/rules/commit-message-convention.mdc index 43eb2eb..66ea7a2 100644 --- a/.cursor/rules/commit-message-convention.mdc +++ b/.cursor/rules/commit-message-convention.mdc @@ -1,18 +1,18 @@ --- -description: Monorepo conventional commit message format +description: Conventional commit message format for the LoBBS plugin repo alwaysApply: true --- # Commit Message Convention -Use monorepo-style conventional commit messages for all git commits. +Use conventional commit messages for all git commits. ## Format `type(scope): subject` - `type` is a conventional commit type like `feat`, `fix`, `chore`, `docs`, `refactor`, or `test`. -- `scope` should identify the monorepo package or area (for example `lobbs`, `meshtastic`, `meshcore`, `repo`). +- `scope` should identify the plugin area (for example `core`, `apps`, `lodb`, `lofs`, `meshtastic`, `meshcore`, `repo`). `meshtastic` and `meshcore` mean the platform providers under `platforms/`. - `subject` must be concise, imperative, and lowercase when possible. ## Limits @@ -21,5 +21,5 @@ Use monorepo-style conventional commit messages for all git commits. ## Examples -- `feat(lobbs): add meshcore platform provider` -- `chore(meshcore): bump pin` +- `feat(meshcore): add chat mesh platform provider` +- `fix(lodb): flush index on record delete` diff --git a/.cursor/rules/lobbs-project.mdc b/.cursor/rules/lobbs-project.mdc index 0a2b45d..e055cf3 100644 --- a/.cursor/rules/lobbs-project.mdc +++ b/.cursor/rules/lobbs-project.mdc @@ -11,20 +11,21 @@ Cross-platform, on-firmware BBS for **Meshtastic** and **MeshCore**. Greenfield: **Plugin owns everything, forks stay upstream.** -1. **Plugin** (`lobbs/`, PlatformIO library): core, apps, LoScalar, LoDB, LoFS, protocol, and the platform providers under `lobbs/platforms//`. On MeshCore the plugin also owns the firmware app (`setup()`/`loop()`). -2. **Firmware forks** ([`meshtastic/`](meshtastic/), [`meshcore/`](meshcore/) submodules, both on `lobbs`): upstream plus one new `variants/lobbs/*.ini` that defines the `*_lobbs` envs and pulls in the plugin. +1. **Plugin** (this repo, PlatformIO library): core, apps, LoScalar, LoDB, LoFS, protocol, and the platform providers under `platforms//`. On MeshCore the plugin also owns the firmware app (`setup()`/`loop()`). +2. **Firmware forks** (`../lobbs-meshtastic-firmware`, `../lobbs-meshcore-firmware`, both on `lobbs`): upstream plus one new `variants/lobbs/` folder that defines the `*_lobbs` envs and pins the plugin in `lib_deps`. -Until extraction finishes, LoBBS code still lives in-tree at `meshtastic/src/modules/LoBBS/`. +The repos are siblings under `/Volumes/Code/repos/meshenvy/`. No submodules anywhere: PlatformIO clones git deps with `--recursive`, and MeshForge builds a fork repo alone. + +Until extraction finishes, LoBBS code still lives in-tree at `../lobbs-meshtastic-firmware/src/modules/LoBBS/`. ## Fork diff policy -- Allowed: one new `variants/lobbs/` ini per fork. +- Allowed: one new `variants/lobbs/` folder per fork (ini, `.gitignore` for the local override, README pointer). - No edits to upstream files. If an extension point is missing, make the smallest possible change, list it in [`README.md`](README.md), and open an upstream PR. -## Workflow +## Pins and releases -- Work inside the submodules; commit and push there, then commit the pin bump here. -- Keep both submodules on `lobbs` (`.gitmodules` `branch = lobbs`). +Local dev uses a gitignored `symlink://../lobbs` override. Committed fork config only ever pins a plugin commit. Tagging and pin procedure: [`release.mdc`](release.mdc). ## Style diff --git a/.cursor/rules/release.mdc b/.cursor/rules/release.mdc new file mode 100644 index 0000000..eac681c --- /dev/null +++ b/.cursor/rules/release.mdc @@ -0,0 +1,46 @@ +--- +description: LoBBS plugin pins, local symlink dev, and release tagging across the plugin and both firmware forks +alwaysApply: true +--- + +# Pins and releases + +Three sibling repos: `lobbs` (plugin), `lobbs-meshtastic-firmware`, `lobbs-meshcore-firmware`. Each fork's `variants/lobbs/` config pulls the plugin through `lib_deps`. + +## Local dev: symlink, never committed + +Point a fork at the working copy with a gitignored override: + +| Fork | Override file | Content | +| --- | --- | --- | +| MeshCore | `platformio.local.ini` (already gitignored, already in `extra_configs`) | `lib_deps` with `lobbs=symlink://../lobbs` | +| Meshtastic | `variants/lobbs/local.ini` (gitignored by `variants/lobbs/.gitignore`, picked up by the `variants/*/*.ini` glob) | same | + +- `symlink://` never appears in a committed file. A pushed symlink breaks MeshForge and CI, because the path only exists locally. +- Before pushing a fork, `git grep -n 'symlink://' -- variants/lobbs` must return nothing. + +## Committed pin + +```ini +lobbs=https://github.com/MeshEnvy/lobbs.git# +``` + +Pin by commit, not branch. A commit pin is immutable, and PlatformIO fetches it without a recursive clone. + +## Tags + +| Repo | Format | Example | +| --- | --- | --- | +| `lobbs` | `vX.Y.Z` | `v2.1.0` | +| `lobbs-meshtastic-firmware` | `lobbs-vX.Y.Z.-meshtastic-v.` | `lobbs-v2.1.0.abc1234-meshtastic-v2.7.15.567b8ea` | +| `lobbs-meshcore-firmware` | `lobbs-vX.Y.Z.-meshcore-v.` | `lobbs-v2.1.0.abc1234-meshcore-v1.9.1.def5678` | + +- `` is the plugin commit the fork pins (the `vX.Y.Z` tag's commit). +- `.` is the upstream release and commit the fork's `lobbs` branch is based on (`git merge-base lobbs upstream/`). +- Annotated tags only (`git tag -a`). + +## Release procedure + +1. Plugin: update `CHANGELOG.md`, commit, `git tag -a vX.Y.Z`, push the tag. +2. Each fork: set the committed `lib_deps` pin to the `vX.Y.Z` commit sha. Confirm no `symlink://` is committed. Build the `*_lobbs` envs from a clean clone. +3. Commit the pin bump, tag with the fork format above, push branch and tag. diff --git a/README.md b/README.md index 6374737..6ff9bd7 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,36 @@ # LoBBS -On-firmware bulletin board for **Meshtastic** and **MeshCore**. This umbrella repo holds the firmware forks as submodules. The portable LoBBS plugin (core, apps, storage, and both platform providers) will live in `lobbs/` once it is extracted from the Meshtastic fork. +On-firmware bulletin board for **Meshtastic** and **MeshCore**. This repo is the portable LoBBS plugin, a PlatformIO library: core, apps, storage, and both platform providers. It is being extracted from the Meshtastic fork. -## Submodules +## Firmware forks -| Path | Repo | Branch | -| --- | --- | --- | -| [`meshtastic/`](meshtastic/) | [MeshEnvy/lobbs-meshtastic-firmware](https://github.com/MeshEnvy/lobbs-meshtastic-firmware) | `lobbs` | -| [`meshcore/`](meshcore/) | [MeshEnvy/lobbs-meshcore-firmware](https://github.com/MeshEnvy/lobbs-meshcore-firmware) | `lobbs` | +| Repo | Branch | +| --- | --- | +| [MeshEnvy/lobbs-meshtastic-firmware](https://github.com/MeshEnvy/lobbs-meshtastic-firmware) | `lobbs` | +| [MeshEnvy/lobbs-meshcore-firmware](https://github.com/MeshEnvy/lobbs-meshcore-firmware) | `lobbs` | -## Setup +Each fork builds standalone. Its `variants/lobbs/` config pins this plugin by commit in `lib_deps`, so cloning one fork is enough to build it. + +## Local development + +Clone the plugin and the forks side by side: ```bash -git clone --recurse-submodules git@github.com:MeshEnvy/lobbs.git -# or, in an existing clone: -git submodule update --init --recursive +git clone git@github.com:MeshEnvy/lobbs.git +git clone -b lobbs git@github.com:MeshEnvy/lobbs-meshtastic-firmware.git +git clone -b lobbs git@github.com:MeshEnvy/lobbs-meshcore-firmware.git ``` -## Workflow +Point a fork at your working copy with a gitignored override that sets `lib_deps` to `symlink://../lobbs`. Committed config always carries the real pin. Details: [`.cursor/rules/release.mdc`](.cursor/rules/release.mdc). -Work inside the submodules. Commit and push there, then commit the pin bump here. +## Releases -```bash -cd meshtastic && git checkout lobbs && git pull --ff-only -# edit, build, commit, push in the submodule -cd .. && git add meshtastic && git commit -m "chore(meshtastic): bump pin" -``` +The plugin is tagged `vX.Y.Z`. Each fork release is tagged `lobbs-vX.Y.Z.--v.`, for example `lobbs-v2.1.0.abc1234-meshtastic-v2.7.15.567b8ea`. Full procedure: [`.cursor/rules/release.mdc`](.cursor/rules/release.mdc). ## Fork diff policy -The forks stay upstream plus one new config file: `variants/lobbs/*.ini`, which defines the `*_lobbs` build envs and pulls in the plugin. No edits to upstream files. If an extension point is missing, the fix is the smallest possible change, listed here and paired with an upstream PR. +The forks stay upstream plus one new folder: `variants/lobbs/`, which defines the `*_lobbs` build envs and pulls in the plugin. No edits to upstream files. If an extension point is missing, the fix is the smallest possible change, listed here and paired with an upstream PR. -Until extraction finishes, LoBBS code still lives in-tree at `meshtastic/src/modules/LoBBS/`. +Until extraction finishes, LoBBS code still lives in-tree at `lobbs-meshtastic-firmware/src/modules/LoBBS/`. Architecture and greenfield rules: [`.cursor/rules/lobbs-project.mdc`](.cursor/rules/lobbs-project.mdc).