Releases and updates

The app repository holds your code and release assets. The catalog repository holds the request to publish a particular release. Every new version needs a catalog pull request, including updates to an accepted app. Choose GitHub CLI or GitHub website for each GitHub operation below. Both methods use Git for local commits, tags and pushes; the website method needs no gh installation.

Store listing

Edit store/storefront.toml and the localized text it contains or references. Replace the template’s title, description, support and privacy links, icon and release notes. The actual app behavior must agree with its listing and permission declarations.

The walkthrough in dayscript/demo.yaml defines named screenshots. Select the captures for each store in store/storefront.toml; the names must match the walkthrough. For example:

[storefront.ios-uikit.apple-app-store.screenshots]
iphone = ["home", "settings"]
ipad = ["home", "settings"]

[storefront.android-mdc.google-play-store.screenshots]
default = ["home", "settings"]

Use names that your walkthrough actually captures. Test each shipped locale. App Store submissions need both required Apple device classes; do not remove the template’s device profiles without checking store requirements. The release’s gallery.json describes which files appear in each listing, and screenshots.zip supplies their bytes.

See Day’s store metadata reference and dayscript guide. Screenshot failures identify the usual mismatches.

Create a release

1. Update the app and listing’s release notes. Run lint and tests, commit your changes, and start with a clean working tree.
2. Bump and push the next patch release:

day metadata --version-bump patch --git-push

Day updates the version in Cargo.toml, the build number in Day.toml, and Cargo.lock, then commits, tags and pushes. Check any build-number overrides in Day-appfair.toml: the effective build number must exceed every binary already uploaded to either store, including unsuccessful submissions.

Use the tag reported by Day in the commands below. These update examples use v0.1.2, following a first release of v0.1.1.

gh run list --repo Orbit-Notes/Orbit-Notes --workflow ci.yml --limit 5

The template’s workflow creates the GitHub release and uploads its assets. It uses release-mode: pre-release: the new version is public but does not replace the current Latest release while the App Fair is reviewing it.

After the tag run finishes, inspect the release assets:

gh release view v0.1.2 --repo Orbit-Notes/Orbit-Notes
gh release view v0.1.2 --repo Orbit-Notes/Orbit-Notes \
  --json assets --jq '.assets[].name'

For both catalog channels, expect the base app’s Android .aab, iOS .ipa, package metadata, and—when replacing screenshots—gallery.json and screenshots.zip. CI may publish other targets too. Read the workflow result, not just the presence of a release page.

After CI finishes, update the release notes:

gh release edit v0.1.2 --repo Orbit-Notes/Orbit-Notes \
  --notes-file release-notes.md

Keep the release’s pre-release status. Pass --tag v0.1.2 explicitly to the catalog helper. Release troubleshooting.

First submission

Check the inclusion criteria, including the required Publisher installation and website. Open a first-app discussion, then prepare the catalog pull request. Both methods require Python 3 with virtual-environment support. The examples use Orbit-Notes and v0.1.1; substitute your app token and release tag. Getting started generates commands for your app.

gh repo fork appfair/appfair-apps --clone --remote -- appfair-submission
cd appfair-submission
git fetch upstream main
git switch -c 'add-Orbit-Notes-v0.1.1' upstream/main
python3 -m venv ../appfair-submit-venv
../appfair-submit-venv/bin/python -m pip install PyYAML
../appfair-submit-venv/bin/python scripts/queue.py add 'Orbit-Notes' --tag 'v0.1.1'
../appfair-submit-venv/bin/python scripts/queue.py validate 'apps/Orbit-Notes.yaml'
git diff -- 'apps/Orbit-Notes.yaml'
cat 'apps/Orbit-Notes.yaml'
git add 'apps/Orbit-Notes.yaml'
git commit -m 'Add Field Notes v0.1.1'
git push -u origin HEAD
GH_USER=$(gh api user --jq .login)
gh pr create --repo appfair/appfair-apps --base main \
  --head "$GH_USER:add-Orbit-Notes-v0.1.1" \
  --title 'Add Field Notes v0.1.1' \
  --body 'Submit Orbit-Notes/Orbit-Notes at v0.1.1. Release: https://github.com/Orbit-Notes/Orbit-Notes/releases/tag/v0.1.1.'

git clone https://github.com/YOUR-LOGIN/appfair-apps.git appfair-submission
cd appfair-submission
git remote add upstream https://github.com/appfair/appfair-apps.git
git fetch upstream main
git switch -c 'add-Orbit-Notes-v0.1.1' upstream/main
python3 -m venv ../appfair-submit-venv
../appfair-submit-venv/bin/python -m pip install PyYAML
../appfair-submit-venv/bin/python scripts/queue.py add 'Orbit-Notes' --tag 'v0.1.1'
../appfair-submit-venv/bin/python scripts/queue.py validate 'apps/Orbit-Notes.yaml'
git diff -- 'apps/Orbit-Notes.yaml'
cat 'apps/Orbit-Notes.yaml'
git add 'apps/Orbit-Notes.yaml'
git commit -m 'Add Field Notes v0.1.1'
git push -u origin HEAD

The file is apps/<token>.yaml. Its core fields are:

token: Orbit-Notes
title: Field Notes
tag: v0.1.1
commit: FULL_40_CHARACTER_COMMIT_HASH
distribution:
  ios-uikit:
    - apple-app-store
  android-mdc:
    - google-play-store

The commit line above is a placeholder. Use the helper to resolve the real hash. Tags can move; the catalog pins a commit so every stage builds the reviewed source. Omit a channel only if you are not submitting to that store. The helper’s generated file needs review before committing.

The catalog contribution reference documents optional fields, upload-only settings, screenshot handling and identity pins. Do not add credentials or choose a signing flavor in this file.

Submit an update

Keep the app token and store identities. Release a new version from the app repository, wait for its assets, then update the existing catalog file.

These commands assume the first submission created appfair-submission/, an origin remote pointing to your personal fork, an upstream remote pointing to the App Fair, and ../appfair-submit-venv/ containing Python and PyYAML. Inspect git remote -v and adapt if your clone differs. Start with a clean working tree.

cd appfair-submission
git remote -v
git fetch upstream main
git switch -c update-Orbit-Notes-v0.1.2 upstream/main
../appfair-submit-venv/bin/python scripts/queue.py update Orbit-Notes --tag v0.1.2
../appfair-submit-venv/bin/python scripts/queue.py validate apps/Orbit-Notes.yaml
git diff -- apps/Orbit-Notes.yaml
git add apps/Orbit-Notes.yaml
git commit -m 'Update Field Notes to v0.1.2'
git push -u origin HEAD

GH_USER=$(gh api user --jq .login)
gh pr create --repo appfair/appfair-apps --base main \
  --head "$GH_USER:update-Orbit-Notes-v0.1.2" \
  --title 'Update Field Notes to v0.1.2' \
  --body 'Release: https://github.com/Orbit-Notes/Orbit-Notes/releases/tag/v0.1.2'

On Windows, use ../appfair-submit-venv/Scripts/python.exe. For an organization-owned fork, use the organization instead of $GH_USER in the CLI command.

Usually only tag and commit change. If the display name changes, update the catalog’s title too; the helper preserves the existing title. Describe behavior changes and link the release notes in the PR. Submission troubleshooting.

Approval and deployment

The catalog separates untrusted app builds from package inspection and credential-bearing signing jobs. It checks package identity and permissions, compares release contents, checks build metadata and scans packages. The comparison allows some flavor-specific differences, including the app’s native binary; it is not a proof that all executable bytes match.

Approval by the App Fair does not replace store review. Apple’s approved version may still require the App Fair to release it; Google’s rollout follows the configured track and review state. There is no fixed review time. Approval and store problems.

The App Fair Publisher installation is required, with access to the app repository. It attaches signed packages and promotes the GitHub pre-release after publication succeeds. That release event can rebuild the app’s website, provided Pages accepts its tag. Signed packages are also retained as workflow artifacts. Installing the publisher is distinct from granting access to any store account.

Retry a failed publication

If source or package changes are needed, fix and commit the app changes, run day metadata --version-bump patch --git-push, wait for CI, and update the catalog PR. Do not replace assets or retag a release that is being reviewed. Duplicate build numbers.