Releases and versioning

Every site deploy and every installer release carries a version and a build number. Agents manage both automatically on every deploy, so the user never has to think about them.

Policy

• Build number: goes up on every deploy. heremyapp assigns site builds itself (1, 2, 3, ...). For installers the build is the app's own build number (for example CFBundleVersion), which you increase before building.
• Version: Semantic Versioning MAJOR.MINOR.PATCH, bumped by what changed since the previous release:

When a release mixes changes, use the largest bump that applies: bug fixes plus dark mode is minor.

Decide the bump yourself from the changes you made or can see (your edits, git diff, git log). Do not ask the user to pick a version; tell them the result in your report. Use a pre-release such as 2.0.0-beta.1 only when the user asks for a beta.

Before every deploy: check the current versions

curl -sS --fail-with-body "$API/spaces/my-app/versions" -H "$AUTH"

{"policy":"Every deploy gets the next build number automatically. ...",
 "site":{"live":{"deployment_id":"dep_5adj...","version":"1.4.2","build":17,"notes":"Fix typo","created_at":"..."},
         "latest":{"deployment_id":"dep_5adj...","version":"1.4.2","build":17,"notes":"Fix typo","created_at":"..."},
         "next":{"build":18,"patch":"1.4.3","minor":"1.5.0","major":"2.0.0"}},
 "artifacts":[{"filename":"MyApp.pkg","latest":{"id":"art_3kq9...","version":"1.2.0","build":"45","status":"active"},
               "live":{"id":"art_3kq9...","version":"1.2.0","build":"45"},
               "next":{"patch":"1.2.1","minor":"1.3.0","major":"2.0.0","build":"46"}}],
 "contact_status":"provided"}

• site.live is what visitors see now; site.latest is the newest deploy (they differ after a rollback). Next numbers always continue from latest.
• For each installer file, latest is the highest version ever published (including deleted ones, whose numbers cannot be reused) and live is what the latest download link serves now.
• contact_status tells you whether to ask the user for contact details (see Landing page checklist).

Deploy a site with its version

Add bump (and a one-line notes summary) to the deploy URL. curl's --url-query encodes the values for you:

tar -czf - -C dist . | curl -sS --fail-with-body -X POST "$API/spaces/my-app/deployments" \
  --url-query "bump=minor" --url-query "notes=Add Japanese page" \
  -H "$AUTH" -H "content-type: application/gzip" --data-binary @-

• curl older than 7.87 has no --url-query: put the values in the URL instead and percent-encode the notes, for example "$API/spaces/my-app/deployments?bump=minor&notes=Add%20Japanese%20page".
• The response includes version and build. Without bump, heremyapp bumps the patch version.
• Send version=X.Y.Z instead of bump to set an exact version; it must be higher than the current one (409 version_not_increasing lists suggestions).
• The first deploy of a space is 1.0.0, build 1.
• Every page of the live site carries X-Heremyapp-Version and X-Heremyapp-Build headers, so you can confirm the new version is live:

curl -sIL https://heremyapp.com/ACCOUNT/my-app | grep -iE "^x-heremyapp-(version|build)"

Release an installer with its version

1. Read the app's current version and build from the project:
   • Xcode: MARKETING_VERSION and CURRENT_PROJECT_VERSION build settings (CFBundleShortVersionString and CFBundleVersion). With Apple Generic Versioning: agvtool what-marketing-version, agvtool what-version.
   • Electron or Node: version in package.json; a build number if the project keeps one.
2. Work out the new numbers from artifacts[].latest (the published release):
   • Version: bump the published version by the policy above. If the project's version is already higher than that (the user or an earlier step set it and it was never published), keep the project's version.
   • Build: one more than the published build, or the project's build if that is already higher.
   • Build numbers compare part by part as numbers (46 < 47, 1.2.9 < 1.2.10). Keep one format per app.
3. Write them into the project (for example agvtool new-marketing-version 1.3.0 and agvtool new-version -all 46, or edit the build settings), then build, sign and notarize.
4. Register the installer with version, build and notes (Installers). heremyapp rejects a version or build that does not increase (version_not_increasing, build_not_increasing, with suggestions).
5. Update the version, size and release notes shown on the landing page, and deploy the site (usually bump=patch, or minor if you added content).

The landing page should show the app's version (from the installer). The site's own version tracks changes to the page itself.