SRM Notes for 03-07-2025

[glopesdev]

Agenda

• 🚀Small Issue (10 min)
• 🚅Medium Issue (20min)
• 🐢Large Issue (45min)

Discussion 🚅

This meeting will continue to focus on using the SoundCard as an exercise for fleshing out the requirements for releasing a complete device. We will address the following points:

Unified Release

Use a single version number in device repositories · Issue #145 · harp-tech/protocol

Prefect reference template

• README.md file must have a clear section title (# instead of ##)
• Avoid # Licensing # as a full section title (also, do we want to keep the symmetrical ##?)
• Review register description writing rules:
  • e.g. currently description is expected to be a sentence starting with a verb.

Consider revising naming of top-level folders · Issue #146 · harp-tech/protocol
Adopt web instead of PascalStyle naming conventions

Pros

• Matches URL conventions
• Matches layout of bonsai-rx repos (easier to maintain as a whole)
• Matches GitHub, dotnet, and other tool naming conventions:
  • .github/workflows
  • .config/dotnet-tools.json
  • .bonsai
  • docs/README.md (special case has to be inside docs folder)

Cons

• Change from what we had before
• Need to change repo template and Generators.csproj paths

Documentation infrastructure

Documentation development roadmap · Issue #27 · harp-tech/device.soundcard

Merge firmware PR

v3.0 firmware release by bruno-f-cruz · Pull Request #20 · harp-tech/device.soundcard

• Sign CLA
• Resolve all review comments
• Regenerate interface

Update firmware tool

firmware, hardware, core versions · Issue #16 · harp-tech/device.soundcard

Automatic firmware builds

• GCC Compilers for AVR® and Arm®-Based MCUs and MPUs | Microchip Technology
• How to setup the AVR toolchain on WSL2 (Windows 10+) | Tony Mitchell

Update generators to include Atmel firmware headers

Add semantic version register by glopesdev · Pull Request #68 · harp-tech/protocol

[glopesdev]

Feedback from SRM:

• Move to single release tag in format v<major>.<minor>.<patch> but keep the per-component tags for internal tracking only (without releases)
• For now the per-component prefixes are:
  • hardware: pcb*
  • firmware: fw*-harp*
  • interface: api*
  • gui: app*
• Rough versioning guidelines:
  • Initial combined version can be either based on firmware or the max of other per-component versions
    • Example: first "combined release" of soundcard would be v3.0.0
  • Mostly following semantic versioning on device.yml:
    • Additions to device.yml > minor bump
    • Breaking changes to device.yml > major bump
    • Everything else usually > patch bump
  • New hardware boards are versioned as new "hardware targets":
    • Each combined release lists all supported hardware targets ("boards")
  • If a completely new board design requires a big change in the interface or firmware we might consider creating a new repository for it, needs to be evaluated case-by-case
  • Conversely, totally new devices (with different interfaces) could share the same hardware PCB ("board")
  • Intention is to ship firmware distributions embedded in the NuGet package with matching versions and check that they match at runtime (with warnings or errors tbd)

Documentation

• Consider moving Data Interface into examples to show how to open and explore data connected
• Move device documentation into the device repository to encourage decoupling
• Consider having an index of all Harp devices (internal or external / community) based off the whoAmI register
  • Add a new field for the docs URL (consider whether we can use project URL for this)
  • Metadata field for deprecated devices
• Version control of documentation:
  • By having tagged releases, we can always build docs for specific versions
    • We can decide when to "release" the docs:
      • Always on releases (this means that to update the docs, you have to make a release)
      • Can allow updates, but then we have to decide how to archive these interim updates

Repository layout

• Consider normalizing layout to lowercase (we can revisit again next time)