Microfirmware Store

What you are actually asking for

The store does not host your files and does not want a copy of them. It keeps a registry of origins, and an origin is two things: who you are, and the URL of the apps.json you already host.

A build job fetches every origin in that registry, merges what it finds into one catalogue per channel, and publishes it. So you are not submitting your apps. You are submitting a pointer to them, and you keep control of what is on the other end.

Before you start

• Your apps.json is reachable at a stable URL Anywhere on the web works. The build fetches it server-side, so there is no CORS requirement and the URL may be HTTP or HTTPS. Keep the URL stable and update the file in place.
• The image and binary URLs inside it are HTTPS A visitor's browser loads those directly, so unlike the catalogue URL itself they cannot be plain HTTP.
• Your app has its own UUID Not the development one from step 6. If yours collides with a SidecarTridge app's UUID, yours is the one dropped.

Fork, and open the right file

Fork this repository, clone your fork, and branch:

git checkout -b add-my-origin

Which file you edit depends on the channel you picked in step 10:

Append your entry

The file has a platform, a channel, and an origins array whose first entry is SidecarTridge's. Add one object to the end of that array, and mind the comma after the entry before yours:

{
  "creator": {
    "id": "retro-homebrew",
    "name": "Retro Homebrew Collective",
    "url": "https://retro-homebrew.example"
  },
  "official": false,
  "enabled": true,
  "url": "https://retro-homebrew.example/atari-st/apps.json"
}

That is the whole change. Four things to get right:

creator also takes an optional image and contact. The full field reference is in CREATORS.md .

Run the check before you push

The pull request runs a required check. You can run exactly the same thing locally, which turns a review cycle into a ten-second loop:

pip install jsonschema                              # enables the strict validator
python3 tools/build_catalog.py --check --strict     # exactly what the PR check runs

A pass ends with one line:

check: OK

Anything else means something is wrong, and the lines above name the file and the rule. Because --strict actually fetches your URL, this also catches a host that is unreachable or a path you mistyped, which is the failure most likely to embarrass you in review.

python3 tools/build_catalog.py --platform atari-st
python3 -m http.server                              # then open http://localhost:8000

Open the pull request

Commit the registry change on its own and open a pull request against main. A reviewer wants three things in the body: the apps.json URL, one line on what your microfirmwares do, and anything unusual they should know.

Opening it triggers the Validate origins check, which validates your registry entry, fetches your apps.json, and validates that too. It must be green before the pull request can merge. If it fails, the troubleshooting table in CREATORS.md maps each message to its cause.

After a maintainer merges it, the build folds your listing into the published catalogue and the site deploys. Your apps appear under your creator name, with a filter for browsing just yours.

What the build does to your data

Your apps.json is not copied verbatim. Four things happen to it, so that every creator's data behaves the same way. None of them is a surprise once you know.

• Your apps are tagged with your creator id and shown under your name.
• Duplicate UUIDs resolve in SidecarTridge's favour. If one of your apps shares a uuid with theirs, yours is dropped. Use your own.
• Device names are rewritten to canonical spellings. For Atari ST those are ST, STE, MegaST, MegaSTE, TT and Falcon. Case, punctuation and a leading platform name are ignored, so Atari MegaST and atari-megast both resolve. A name matching nothing is kept as written and reported in the log, never discarded, but it will appear in the store as its own filter entry.
• description is sanitised to a whitelist of tags when it is rendered.

Afterwards

You are done with this repository. To ship a new version, bump version.txt, rebuild, upload the new .uf2, and update your own apps.json in place at the same URL. The store rebuilds daily and picks it up. Ask a maintainer if you need it sooner.