GRMrGecko/midi-harbor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
midi-harbor/specs/README.md
James Coleman 5dce49ee43 feat(update): say when the daemon is another build and update it on request 
- A daemon keeps running the copy it was started from, so after an update the old one ran until the next login and nothing said so; clients compared only the major protocol version. Every build now carries a UUID, the daemon reports it as ServerInfo.build_id under protocol 1.3, and a daemon too old to report one counts as outdated.
- The window shows a notice above every page when the daemon it reached is another build, with both versions. Update now registers the copy that was opened as the service and restarts the daemon from it; Not now puts the notice away. Nothing is restarted unless the user asks, so two copies open at once cannot replace each other's daemon in turn. A newer daemon is offered as Use this version, and one the service did not start, or one reached with --socket, gets no button.
- service install --start now stops a running daemon before registering and starting, so the daemon started is the program that was asked. Under systemd and Task Scheduler it used to rewrite the registration and leave the old daemon running, since starting a running service does nothing.
- service status says when the daemon is another build than the program asked, and --json carries same_build.
- The App Store app stops a daemon another build of the app left running and starts its own, instead of attaching to it.
- Packaging sets MIDI_HARBOR_BUILD_ID once for everything a run builds, because the App Store app, its helper and each architecture are compiled separately and must agree. Packages of one release share an identifier, so neither replaces the other's daemon.
2026-10-02 11:56:27 -05:00

7.4 KiB
Raw Blame History

Specifications

One spec per capability, numbered by topic. Each holds its user stories, requirements, success criteria, research and tasks; the architecture, the daemon contract and the command-line contract are in 001, and every spec follows the constitution.

Requirement (FR), success criterion (SC), research (R) and task (T) numbers are unique across every spec, and the code cites them by number. They were given in the order the work was done, so one spec's numbers are not contiguous; the lists below say which spec holds each. The one exception is 014, whose task list started again at T001: its T001 to T034 are cited as 014's.

Spec What it covers
001-service-and-clients The single executable, the daemon, the gRPC contract, the command line, installing the service, packaging; the architecture and the original input
002-configuration The configuration file, applying changes while running, export and import, Apple's setup, capabilities
003-virtual-ports Ports applications on one computer use to talk to each other
004-hardware-devices Attached MIDI hardware and other applications' ports, hot-plug, identity
005-network-ports RTP-MIDI between computers: discovery, invitations, the journal, machines, the automatic port
006-bluetooth-midi Bluetooth LE MIDI, connecting out and advertising
007-routing Routes between any two endpoints, loops, system-exclusive, the repeater
008-resilience Recovery: backoff, sleep and wake, releasing notes, restoring state, the MIDI service dying
009-observability State, counters, history, the monitor, the diagnostic report
010-graphical-interface The libcosmic window and its redesign
011-midi-service-crash-warning Warning that other apps may have lost MIDI; when traffic last moved each way
012-test-note Sending a note out of an endpoint to test what listens
013-windows-support Windows as a first-class platform
014-mac-app-store-mode The sandboxed App Store build, run from the menu bar
015-mac-menus The menus on macOS: File, Edit, View, Window and Help
016-app-store-submission Building the package App Store Connect takes
017-appimage The AppImage for Linux, and registering the daemon from it
018-remembered-machines Machines a network port connected to: forgetting old connections, following a session that moved, proving which port a session is; answering Apple over a link-local address
019-daemon-updates Telling that the daemon is another build than the window, and updating it when asked

Where each number is

001-service-and-clients

  • Requirements: FR-036–FR-039, FR-039a, FR-039b, FR-039c, FR-039d, FR-039e, FR-039f, FR-039g, FR-039h, FR-040–FR-043
  • Success criteria: SC-010, SC-014, SC-014a, SC-014b, SC-014c, SC-016
  • Research: R-003, R-007–R-009, R-012, R-023, R-028, R-042, R-052–R-054, R-059, R-081
  • Tasks: T001–T006, T009–T016, T028–T035, T038–T039, T041–T060, T063, T146–T147, T151–T154, T157, T166–T167, T172, T241

002-configuration

  • Requirements: FR-049–FR-053
  • Success criteria: SC-015
  • Research: R-011, R-043, R-061
  • Tasks: T022–T026, T040, T061–T062, T149–T150, T173–T174

003-virtual-ports

  • Requirements: FR-001–FR-002, FR-002a, FR-003–FR-007
  • Success criteria: SC-001, SC-002, SC-008
  • Research: R-002, R-014, R-048
  • Tasks: T064–T070, T072–T076, T161, T182, T197

004-hardware-devices

  • Requirements: FR-015a, FR-015b, FR-015c, FR-015d, FR-015e, FR-015f, FR-015g
  • Success criteria: SC-010a, SC-010c
  • Research: R-013, R-024, R-027, R-038–R-040, R-047, R-055
  • Tasks: T104, T107–T111, T116, T119, T158, T188, T190, T193

005-network-ports

  • Requirements: FR-008–FR-015, FR-015h, FR-015i
  • Success criteria: SC-003, SC-006, SC-009, SC-011
  • Research: R-004, R-005, R-015–R-016, R-017–R-018, R-020–R-022, R-036–R-037, R-046, R-049, R-056–R-057, R-060, R-063, R-065–R-066, R-068, R-071, R-073, R-076, R-080, R-082
  • Tasks: T007, T077–T082, T082a, T083–T096, T100–T103, T159, T168, T176, T179, T181, T184–T187, T191, T196, T198–T200

006-bluetooth-midi

  • Requirements: FR-016–FR-021
  • Research: R-006, R-041, R-058, R-064, R-075, R-077
  • Tasks: T008, T037, T128–T137, T156, T162, T169–T171, T175

007-routing

  • Requirements: FR-030, FR-030a, FR-030b, FR-031–FR-034, FR-034a, FR-035
  • Success criteria: SC-010b
  • Research: R-019, R-029–R-030, R-032, R-062
  • Tasks: T105–T106, T111a, T112–T115, T117–T118, T160, T177, T183

008-resilience

  • Requirements: FR-022–FR-029
  • Success criteria: SC-004, SC-005, SC-007
  • Research: R-010, R-031, R-033–R-035, R-044–R-045, R-050–R-051, R-067, R-069–R-070, R-072, R-074, R-079
  • Tasks: T017–T020, T020a, T021, T036, T071, T071a, T097–T099, T127, T148, T155, T192, T195

009-observability

  • Requirements: FR-044–FR-048
  • Success criteria: SC-012, SC-013
  • Tasks: T027, T120–T126, T163–T165, T178, T194

010-graphical-interface

  • Research: R-001, R-025–R-026, R-078
  • Tasks: T138–T145, T180, T189, T240

011-midi-service-crash-warning

  • Requirements: FR-M01, FR-M02, FR-M03, FR-M04
  • Success criteria: SC-M01, SC-M02
  • Research: R-101
  • Tasks: T236–T238, T242–T243

012-test-note

  • Requirements: FR-N01, FR-N02
  • Success criteria: SC-N01
  • Tasks: T239

013-windows-support

  • Requirements: FR-W01, FR-W02, FR-W03, FR-W04, FR-W05, FR-W06, FR-W07, FR-W08, FR-W09, FR-W10, FR-W11, FR-W12
  • Success criteria: SC-W01, SC-W02, SC-W03
  • Research: R-083–R-093
  • Tasks: T201–T226, T227–T228, T229–T230, T231–T235

014-mac-app-store-mode

  • Requirements: FR-A01, FR-A02, FR-A03, FR-A04, FR-A05, FR-A06, FR-A07, FR-A08, FR-A09, FR-A10, FR-A11, FR-A12, FR-A13, FR-A14
  • Success criteria: SC-A01, SC-A02, SC-A03, SC-A04, SC-A05
  • Research: R-094–R-100
  • Tasks: T001–T034

015-mac-menus

  • Requirements: FR-U01, FR-U02, FR-U03
  • Success criteria: SC-U01
  • Research: R-102
  • Tasks: T244

016-app-store-submission

  • Requirements: FR-S01, FR-S02, FR-S03
  • Success criteria: SC-S01
  • Research: R-103
  • Tasks: T245

017-appimage

  • Requirements: FR-I01, FR-I02, FR-I03, FR-I04
  • Success criteria: SC-I01
  • Research: R-104
  • Tasks: T246–T248

018-remembered-machines

  • Requirements: FR-P01, FR-P02, FR-P03, FR-P04, FR-P05, FR-P06, FR-P07
  • Success criteria: SC-P01, SC-P02
  • Research: R-105–R-107
  • Tasks: T249–T252

019-daemon-updates

  • Requirements: FR-B01, FR-B02, FR-B03, FR-B04, FR-B05, FR-B06, FR-B07
  • Success criteria: SC-B01, SC-B02
  • Research: R-108
  • Tasks: T253