The Publish Flow

Editing a mod in Edit Mode drives two distinct kinds of push to GitHub: a background checkpoint that happens automatically while you work, and an explicit publish that you trigger when the mod is ready for other people. Only one of the two makes the mod playable in multiplayer.

Checkpoints: your safety net, not your release#

Every edit marks the draft dirty. Ten seconds after edits settle, the editor pushes a checkpoint commit to the mod's wip branch — debounced so a burst of changes collapses into one push rather than one per keystroke. If a checkpoint push fails (for example, a transient conflict right after a publish touched the same branch), the editor retries once, at three times the normal delay, without waiting for you to make another edit.

Checkpoints exist so your work is never sitting only in the browser. They are intentionally not a release action: pushing to wip does not merge to main and does not register the mod, so nothing you checkpoint is visible to other players until you publish. See wip and main for the full two-branch model, including why checkpoints only send the files that actually changed.

The publish-readiness gate#

Before the Publish button will do anything, the mod's manifest must satisfy the same discovery requirements as the mods library: a title, a summary, a square cover image, and at least one screenshot. If any are missing, Publish stays disabled and the dialog lists exactly what to add in Mod Details (the manifest editor's Details tab).

The version number#

The Publish dialog has a Version field, filled in with whatever your manifest's version currently says. It is semver — 1.0.0, or 1.2.0-beta.1 — and the field refuses anything else, because the manifest schema would too.

Editing it is a real edit, not a setting that only applies to this publish: when you leave the field (or press Enter), the editor writes the new number into diceytable.mod.json, saves the draft, and checkpoints it to wip straight away rather than waiting for the usual ten-second debounce. Clicking Publish with a number still being typed is safe — the publish waits for that save before it pushes anything, so the tree it promotes always carries the version you can see.

A published version is permanent. Once a version has been published, it resolves to one specific commit forever, and nothing you do later can repoint it — that is what makes it safe for another pack to depend on yours. So the dialog asks the server, as soon as you open it, what main already ships and what the registry already has a row for. If the number in the field matches either, you get a warning under the field telling you to bump it. Publish anyway and the server refuses the merge, before main moves — but the warning is there so you find out while the field is still in front of you.

Bumping the number clears the warning immediately; there is no need to wait for another round trip.

What happens when you click Publish#

Publishing is three steps, in order, and each one only runs if the previous one succeeded:

Push to wip. Your current tree is compared file by file against what wip actually holds on GitHub, and every file whose content differs is committed. Because the comparison is against the branch itself rather than against earlier checkpoints, the branch that's about to become live cannot be missing an asset.
Merge wip into main. The server asks GitHub to merge the branch. If main was already up to date with wip, nothing changes and the dialog says so instead of claiming a fresh publish. If the merge can't fast-forward, you'll see a merge-conflict error — this can happen if you (or a collaborator) edited files on main directly on GitHub outside the editor.
Register (and re-scan) the mod. The editor immediately calls mod registration against the just-merged main branch. This is what makes the mod appear, playable, in the mods library — see Registration & Multiplayer Play for what that unlocks and why it's required.

Watching a publish#

While a publish runs, the dialog shows a progress bar and a checklist of its phases, with the running one marked:

Save changes — flushes open editor tabs and saves the draft.
Compare with GitHub — hashes each local file against what wip already holds (12/40 counts the files checked). Only files whose content differs are sent.
Upload files — only for a publish too large for one request; files go up one at a time and the list shows each one as queued, sending or sent. Otherwise this phase is struck through as skipped.
Commit to work branch — the commit to wip, listing every file it adds, changes or deletes.
Merge into release branch — the wip → main merge, listing the files GitHub reports the merge changed (the first 200 on a very large merge).
Register & scan — including any "GitHub is still catching up" retries.

Click a finished phase to see its file list again. If a phase fails, it turns red and shows the reason, and the bar stops where the publish did. Closing the dialog does not cancel a publish; reopen it to keep watching.

If the push and merge succeed but registration fails (a network blip, a scanner outage), the dialog tells you plainly: the mod is published to main, but you'll need to add it manually from the mods library, because pushing files to GitHub alone does not make a mod playable.

If registration succeeds but the scanner finds a problem with what you published, the status line reports the scan status and the first compatibility issue rather than silently claiming success — a mod can be pushed to main and still come back incompatible. See the scanner reference under Mod Files → Scanner for what gets rejected and why.

Your repository page is generated too#

Your mod's GitHub repository is a public page, and for most people it is the first one they find. So every publish rewrites two things on it from your manifest, and keeps rewriting them so they can never drift from what Mod Details says:

README.md — the mod's name as the heading, then one sentence saying what kind of pack this is and that it runs on DiceyTable (linking the site), then a prominent link to your mod's own page — /games/<slug> for a game, /mods/<slug> for a table, room or asset pack — and then your description, exactly as you wrote it in Mod Details. Its markdown is passed through untouched, so lists, headings and links survive.
The repository's Website field — pointed at that same mod page, so GitHub's own repo header links to it. This needs admin rights on the repository; if your account only has push access the publish still succeeds and the field is left alone.

Because these are regenerated, README.md is read-only in the editor and never takes part in sync conflicts: change the description, the category, the pack type or the URL slug in Mod Details, and the next publish carries all of it across. A publish that changes nothing about them rewrites nothing — the file's content hash is unchanged, so it stays out of the commit.

If your manifest doesn't parse, no README is generated and whatever the repository already has is left alone; the scanner reports the manifest problem instead.

After publishing#

The published repository is remembered on the mod's project record, so the next time you open it in the editor you don't need to re-link or re-type the repo. Closing Mod Details after making changes also triggers a save-and-checkpoint automatically, so you don't have to remember to hit Save before it's safe to walk away — but remember that still only reaches wip. Nothing is live for other players until you publish.