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
2.6 KiB
Cutting a release
Releases are produced by pushing a cmesh-bot-vX.Y.Z tag. The
.github/workflows/release.yml workflow then:
- Builds every companion USB+BLE environment exposed by the pinned MeshCore submodule (133 boards as of this writing).
- Splits the build across 8 parallel matrix shards for wall-time.
- Embeds the tag version (
vX.Y.Z) into the firmware viaFIRMWARE_VERSION. - Uploads each shard's artifacts.
- 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
mainis green (host tests + representative builds). - You've updated
CHANGELOG.mdwith notes for the new version. - Your local branch is up to date with
origin/main.
Steps
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:
- Mark it as a pre-release (don't delete — flashed devices may still reference the URL).
- Tag and publish
cmesh-bot-vX.Y.(Z+1)immediately. - Edit the broken release's notes to point at the fix.
If you tagged the wrong commit and the workflow hasn't finished:
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.