mirror of
https://github.com/Colorado-Mesh/meshcore-bot-firmware.git
synced 2026-08-11 16:20:29 +00:00
15c7072d81
Adds the project metadata and CI/release workflow needed to publish this repo under Colorado-Mesh/meshcore-bot-firmware. - LICENSE: MIT with attribution to upstream MeshCore (also MIT) - README: rewritten with badges, supported boards, install paths (web flasher / PlatformIO / esptool), bot command table, layout map, development quickstart - CONTRIBUTING: submodule + patch-queue workflow, what-goes-where, patch hygiene rules, PR expectations - RELEASE: cmesh-bot-vX.Y.Z tag scheme + procedure - CHANGELOG: Keep-a-Changelog format, seeded with the hop-coordination fix and patch-5 utility commands - Issue templates: bug_report (with bot stats prompt), feature_request, config.yml (no blank issues, link to upstream + community) - Pull request template: layer checklist, verification gates, prefs-schema impact prompt - .github/workflows/firmware-build.yml: keep PR check on representative envs (Heltec V3, RAK 4631 USB+BLE), add concurrency cancellation for PRs, scope cache key to PIO config hash - .github/workflows/release.yml: NEW; triggers on cmesh-bot-v* tag or manual dispatch, enumerates all 133 *_companion_radio_(usb|ble) envs from vendor/MeshCore/variants/, shards across 8 parallel matrix jobs, aggregates artifacts into a single draft release - scripts/verify.sh: respect MESHCORE_SKIP_APPLY_PATCHES like build-representative.sh does, so verify works when vendor already has patches applied as commits - .gitignore: add .forge.bak.*/ for forge backup directories
82 lines
2.6 KiB
Markdown
82 lines
2.6 KiB
Markdown
# Cutting a release
|
|
|
|
Releases are produced by pushing a `cmesh-bot-vX.Y.Z` tag. The
|
|
`.github/workflows/release.yml` workflow then:
|
|
|
|
1. Builds **every** companion USB+BLE environment exposed by the pinned
|
|
MeshCore submodule (133 boards as of this writing).
|
|
2. Splits the build across 8 parallel matrix shards for wall-time.
|
|
3. Embeds the tag version (`vX.Y.Z`) into the firmware via
|
|
`FIRMWARE_VERSION`.
|
|
4. Uploads each shard's artifacts.
|
|
5. Aggregates everything into a single GitHub Release in draft state,
|
|
ready for you to add release notes and publish.
|
|
|
|
## Prerequisites
|
|
|
|
- All PRs for the release are merged to `main`.
|
|
- CI on `main` is green (host tests + representative builds).
|
|
- You've updated `CHANGELOG.md` with notes for the new version.
|
|
- Your local branch is up to date with `origin/main`.
|
|
|
|
## Steps
|
|
|
|
```sh
|
|
git checkout main
|
|
git pull origin main
|
|
|
|
# Bump CHANGELOG.md, commit, push.
|
|
$EDITOR CHANGELOG.md
|
|
git commit -am "docs: prep cmesh-bot-vX.Y.Z release notes"
|
|
git push origin main
|
|
|
|
# Tag and push.
|
|
git tag -a cmesh-bot-vX.Y.Z -m "Colorado Mesh Bot Firmware vX.Y.Z"
|
|
git push origin cmesh-bot-vX.Y.Z
|
|
```
|
|
|
|
The `release.yml` workflow will start automatically. Track progress at
|
|
<https://github.com/Colorado-Mesh/meshcore-bot-firmware/actions>.
|
|
|
|
When the workflow finishes, a **draft** release will appear at
|
|
<https://github.com/Colorado-Mesh/meshcore-bot-firmware/releases>.
|
|
Review it, paste in the CHANGELOG entry as the description, and publish.
|
|
|
|
## Tag scheme
|
|
|
|
- `cmesh-bot-vX.Y.Z` — production release.
|
|
- `cmesh-bot-vX.Y.Z-rc.N` — release candidate (still publishes as draft).
|
|
- `cmesh-bot-vX.Y.Z-alpha.N` / `-beta.N` — pre-release, mark as
|
|
pre-release when publishing.
|
|
|
|
The leading `cmesh-bot-` namespace leaves room for future variants
|
|
(repeater, room-server) without colliding.
|
|
|
|
## Versioning
|
|
|
|
Semantic-ish: bump major for breaking pref/protocol changes, minor for
|
|
new commands or boards, patch for fixes. Bump `BOT_PREFS_VERSION` in
|
|
`vendor/MeshCore/examples/companion_radio/BotTypes.h` whenever an
|
|
existing pref field's meaning or default changes — that forces deployed
|
|
bots to reset prefs on first boot.
|
|
|
|
## Hotfix / unpublish
|
|
|
|
If a published release turns out to be broken:
|
|
|
|
1. Mark it as a pre-release (don't delete — flashed devices may still
|
|
reference the URL).
|
|
2. Tag and publish `cmesh-bot-vX.Y.(Z+1)` immediately.
|
|
3. Edit the broken release's notes to point at the fix.
|
|
|
|
If you tagged the wrong commit and the workflow hasn't finished:
|
|
|
|
```sh
|
|
git tag -d cmesh-bot-vX.Y.Z
|
|
git push --delete origin cmesh-bot-vX.Y.Z
|
|
# fix, re-tag, re-push
|
|
```
|
|
|
|
Avoid deleting tags after the workflow has published artifacts — users
|
|
may have already downloaded them.
|