Publishing a theme

There are two ways to give somebody a theme, and only one of them involves anybody else.

Hand them the file. A .css under 500 KB is the whole thing. They upload it under Settings → General → Style and that is that: no account, no review, no version number. If you made it for one person or one project, stop reading here.

Submit it to the registry. That puts it in the theme browser inside the app, with your preview image, installable in one click and updatable later. It costs you a pull request and a review.

What the registry is

One JSON file on the master branch of a public repository, which the app downloads directly:

Your files never live there. The registry holds a pointer to your own repository plus a hash, and the app fetches the stylesheet from your GitHub release. So publishing an update means editing two repositories, and getting a version string wrong in either one is the failure worth understanding before you start.

The submission

1. A public repository

Four files at the root:

theme.css      the stylesheet
theme.json     the manifest
preview.png    a screenshot, 800 × 600 recommended
README.md      what it looks like, who it is for, which licence

The id in theme.json has to be unlike anybody else’s, and your licence has to allow other people to pass the theme on. The repository has to stay public, because the app fetches from it on every install, not just once.

2. A release, with exactly these asset names

Tag the release with your version string, then attach the files. The app works out each URL by filling in a fixed pattern, so these names are not a convention. They are how it finds anything at all:

where asset is each of these, spelled exactly:

theme.jsontheme.csspreview.png

A file called MyTheme-v1.css is a file the app will never ask for.

git tag 1.0.0 && git push --tags

3. The hash

Community themes are checked when they are downloaded. Hash the exact file you uploaded to the release, not the one sitting in your working copy:

shasum -a 256 theme.css

4. The pull request

Fork fnadalrod/Releases-Tintero and add your entry to the themes array in themes/theme-list.json:

{
  "id": "midnight-harbour",
  "repository": "https://github.com/you/midnight-harbour",
  "version": "1.0.0",
  "hash": "6f089154fa2a3ce8c44c26293fcd222334ee6164ff9cd9eade1ef7a44c689869"
}

Four fields, and id has to match the one in your theme.json. A person reviews it by hand. There is nothing automated on that repository, and a theme is unsandboxed CSS running against the real app, so somebody reads it. Expect questions about anything that is not a variable.

Once it merges, the theme is live for everyone the next time the app fetches the list.

Shipping an update

Bump all three version strings, cut a new release with the same file names, then open a second pull request changing version and hash in your registry entry.

The app compares the version somebody has against the version in the registry as plain strings and offers an update when they differ. It never works out which one is newer, so 1.0.10 after 1.0.9 is fine, and so is going backwards, which will cheerfully present itself as an update. Semantic versioning is a habit here, not something anybody checks.