v0.3.0 — Development-channel updates actually work

Gives the Development channel a real version axis. Development-channel updates did not work at all before this; on Stable nothing changes.

For a masjid

Nothing changes on Stable. catalog.json on the stable channel is byte-identical to the previous release — same four apps, same versions, same digest-pinned images.

If you use the Development channel, this is the release that makes it work. Until now, when an app published a new development build, nothing in the catalog changed: the version number stayed the same and the image reference stayed the same. OpenMasjidOS spots an update by comparing the version it is offered against the version you have installed, so there was nothing to compare. You were never told a new build existed, and the update button had nothing to point at.

Development builds now carry their own version numbers — 0.11.0-dev.1, then -dev.2, and so on — sitting between the last release and the next one. So the App Store can tell you a new build is there, and tell you which one you are on.

What was wrong

Two faults at once, on every app. The development entry declared the same version as the released entry, so there was nothing to compare. And it pointed at a moving image label rather than a fixed one, so the catalog named one build while installing whatever that label happened to point at that day — "what you were told about" and "what you got" were two different things.

The contract now

A development entry must give the platform the same two things a release entry gives it:

1. A distinct prerelease version — X.Y.Z-dev.N, never equal to the released version, ordered between the last release and the next.
2. An immutable image for every service — either a digest, or a tag matching that entry's version exactly. Never a moving label.

An entry that fails either test is not published. The catalog serves that app's released version on the Development channel instead, with a warning naming the repository, so the channel stays usable while apps migrate one at a time. Three of the four apps migrated while this was being written.

Also in this release

Because the catalog now pins an exact image tag, it checks the image is actually there before publishing. One app declared a new development version minutes before its build had finished uploading, and the catalog briefly offered an entry no masjid could install. It now notices, and serves the released version until the image lands. A network problem or rate limit is treated as "don't know" rather than "missing", so a flaky connection can never demote an app.

For an app author

Your dev branch needs a prerelease version in manifest.yaml, an image published under that exact version, and a compose that references that exact tag — or a digest — for every service. Publishing a :dev alias for humans is fine; it just must not be what the compose names. Publish the image before the entry. Full details in docs/BUILDING_AN_APP.md §8b.

This supersedes guidance in v0.1.0 and v0.2.0 which said a moving :dev tag was expected on the development channel, and that equal versions across channels were fine. Both were true under the old model and are wrong now; the docs have been corrected.

Verification

Built and checked on Linux Node 20 against the live app repositories. The development channel now serves Display 0.67.0-dev.1, Donations 0.41.0-dev.1 and Students 0.46.0-dev.1, each pinning its exact version tag, with Kiosk on its released 0.10.2 until its development image is published — all four verified installable. The stable-channel build is byte-identical to the published catalog. 201 tests pass, twelve of them new. The release was also put through an independent adversarial review, which found one real documentation contradiction in the authoritative contract document; that is fixed here.

v0.2.0 — No more dev-channel downgrades

Fixes the Development channel offering app downgrades, and stops the dev catalog going stale again.

For a masjid

Nothing changes on Stable. catalog.json on the stable channel is byte-identical to the previous release — same four apps, same versions, same images.

If you use the Development channel, this is worth having. For about half a day, switching to Development offered to move your apps backwards — Display 0.66.1 → 0.66.0, Donations 0.40.1 → 0.40.0, Kiosk 0.10.2 → 0.10.1 — and the newest Students work wasn't reachable at all. That is fixed, and the dev channel now refreshes hourly instead of daily.

What went wrong

The dev catalog was built once and then never rebuilt. Nothing was wrong with any app: every app's dev branch was already up to date. The catalog only rebuilt itself when this repository's own dev branch was pushed, while the three app releases were recorded directly on main — so the dev channel simply kept serving what it had built that morning.

The fix, in two parts

A freshness floor. The dev channel now compares each app's development version against its released version and publishes whichever is newer. If an app's dev branch has fallen behind its own release — normally because a fix went straight to the release and was never merged back — the dev channel quietly serves the released version for that app instead, and the build says so. The dev channel therefore cannot offer an older version than stable, by construction rather than by good fortune.

An assertion behind it. After the catalog is built, every entry is checked against its released version and the build fails outright if any is behind. This mirrors the existing rule in the other direction: the stable channel refuses to publish development content, and the development channel refuses to publish anything older than stable.

Prevention and detection deliberately: failing the build alone would have left the stale catalog published, which was the original problem.

Staying fresh

• The rebuild runs hourly rather than daily.
• A stable release now also rebuilds the dev channel — a release invalidates the dev catalog, because apps without a dev branch fall back to their release and every dev entry is floored at its released version.
• App repositories can trigger a rebuild immediately when they push to their dev branch; docs/BUILDING_AN_APP.md §8b has the recipe.

For an app author

Keep your dev branch at or ahead of your release. If it declares an older version, the catalog will not publish it — it serves your release on the dev channel instead, with a warning — because publishing it would offer a masjid a downgrade.

You do not need a different version number on dev. OpenMasjidOS compares channels rather than version numbers, so the same version on both branches is fine and is normal for a moving :dev tag. (This corrects guidance in v0.1.0 which said versions should differ.)

Verification

Built and checked on Linux Node 20 against the live app repositories. The dev channel now resolves Display 0.66.1, Donations 0.40.1, Kiosk 0.10.2 and Students 0.47.0 — at or ahead of stable for every app. Both new layers were made to fire deliberately: pointing an app's dev reference at an older tag produced a fallback to the release rather than a downgrade, and removing the floor made the build fail as intended. The stable-channel build is byte-identical to the published catalog. 189 tests pass, nine of them new, including one that asserts this exact regression app by app.

v0.1.0 — Two update channels

The first tagged release of the OpenMasjidAPPS catalog. It carries the two update channels — stable and dev — and the tooling that keeps them apart.

For a masjid

Nothing you install changes in this release. catalog.json is byte-identical to what it was before, and the same four apps are listed: OpenMasjid Display, Donations, Kiosk and Students.

What is new is that OpenMasjidOS's Update Channel setting now has a catalog to point at. Stay on Stable and nothing about your masjid changes. Switch to Development and your App Store lists the same apps built from each app's dev branch — useful for testing, and not what you want on the screens in the prayer hall.

For an app author

registry.yaml now holds both channel addresses per app:

  - id: kiosk
    repo: OpenMasjid-Solutions/OpenMasjidKiosk
    ref: v0.10.1                    # stable — a release tag, never a branch
    commit: 1c9f3c55…                # the immutable SHA that tag is at
    dev_ref: dev                     # dev channel — a moving branch, by design

• ref must now be a release tag or a commit SHA. A branch there is a build failure — it would make the stable catalog silently follow a moving branch. Branches belong in dev_ref.
• To ship on the dev channel your repo needs a dev branch, a :dev image published from it, that tag referenced in the dev branch's compose, and dev_ref on your registry entry. Miss any of it and you still appear on the dev channel — the build falls back to your stable release.
• Open PRs against dev, not main.

Full contract: docs/BUILDING_AN_APP.md §8b and CLAUDE.md §3b.

The rule the tooling exists to enforce

main/catalog.json is fetched directly by every masjid with no build or deploy step in between, so a dev image landing there would be live immediately. Three independent gates prevent it: the build fails on a dev ref or dev-tagged image in the stable channel; lint fails when a committed catalog carries dev images and the channel is stable (it runs on pull requests using the base branch, so a dev → main PR is red until its catalog is rebuilt); and CI publishes one channel per matrix leg, each asserting HEAD matches its branch and pushing with an explicit refspec.

Also in this release

• CI actions bumped — actions/checkout v7.0.1, actions/setup-node v7.0.0, clearing the Node 20 deprecation warning. Both stay SHA-pinned.
• Dependabot points at dev, so routine bumps no longer need a release to land.
• README rewritten to match the actual feature set: the app list, the full Fabric opt-in surface (sso, notifications, stripe, domain, email, alerts, the app-to-app broker, tunnel, https), what the build refuses, and the npm scripts.
• Branching policy written down: dev is the working branch, main moves only for a release.

Verification

Built and checked on Linux Node 20, the version CI uses: 180 tests, lint clean as the stable channel, the main-channel rebuild byte-identical to the published catalog, and the dev channel resolving all four apps to their dev branch and :dev image. The release also went through an adversarial review — four independent reviewers, 12 findings, all refuted under verification; the one real residual it surfaced (a release-branch lint gap) is fixed here.