Repository navigation
Closed
Description
Complete the steps below to release a new version of ODK Central. For a patch release, use the Patch release issue template instead.
Legend
- 🔎 Requires the second person (reviewer)
Releasing requires two people: one person to push PRs and complete other tasks and another person to review the PRs.
Steps
- Decide the release version (
vXXXX.X.0). The same version is used forcentral,central-backend, andcentral-frontend, so thecentralrelease URL (https://github.com/getodk/central/releases/tag/vXXXX.X.0) can be referenced from thecentral-frontendandcentral-backendrelease bodies. - Write an announcement about the release for the forum.
- Create a new topic in the forum for the release. Use the Scheduled category and add the
odk-centrallabel.
Get the repository
- Get the latest version of the
centralrepository locally.- If you have not cloned the repository: clone it.
- If you had already cloned the repository:
git pull
- Check out the
nextbranch.
Release central-frontend
Releases always include
central-frontend.
- Run
npm run versionincentral-frontend, thennpm install. This consumes the.changeset/files, bumps package versions, updates eachCHANGELOG.md, and updatespackage-lock.json. - Commit the changes on a new branch (e.g.,
release-version-bumps) and open a PR targetingmaster. - 🔎 Review the PR. Verify the version bumps and
CHANGELOG.mdentries match what's expected from the.changeset/files, and thatpackage-lock.jsonwas updated. - Merge the PR.
- In
central-frontend, create a minimal GitHub release on the merged commit. The tag push is what triggers.github/workflows/wf-publish.ymlto publish packages to npm — full release notes live only in thecentralrelease.- Tag:
v*.*.*(no pre-release suffix). - Set as the latest release. Don't set as a pre-release.
- Body: a single line pointing to the upcoming
centralrelease, e.g.,See release notes at https://github.com/getodk/central/releases/tag/vX.Y.Z.
- Tag:
- Wait for
wf-publish.ymlto complete, then verify:- The Actions run finished green.
- The expected packages were published to npm.
- Per-package tags were pushed to the repository.
- If the workflow fails, do not proceed with the rest of the release — investigate and resolve before creating the
centralrelease.
Release central-backend
Releases always include
central-backend.
- Create a GitHub release on the latest
mastercommit ofcentral-backend.- Tag:
v*.*.*(no pre-release suffix). - Don't forget the final
XXXX.X.0in the tag and release title. - Set as the latest release. Don't set as a pre-release.
- Body: a single line pointing to the upcoming
centralrelease, e.g.,See release notes at https://github.com/getodk/central/releases/tag/vX.Y.Z.
- Tag:
Update versions
-
cd serverand run:git fetchgit switch -d origin/masterorgit checkout origin/master
- Update
FRONTEND_VERSIONindocker-compose.ymlto the tag of thecentral-frontendrelease created above. - Commit the updates using a new branch (e.g.,
update-versions). Create a new PR for the branch.- Target the
nextbranch.
- Target the
- 🔎 Review the PR. Verify that the
serverdiff links to the expected commit hashes and thatFRONTEND_VERSIONmatches thecentral-frontendrelease tag.
Merge
- Once the versions PR has been merged into the
nextbranch, use the existing release PR to mergenextinto themasterbranch.- Select "Create a merge commit" when you merge.
- Don't delete the
nextbranch after merging.
Release central
-
Create a GitHub release for
central. This will also create a Git tag.- Don't forget the final
XXXX.X.0in the tag and release title. - Set as the latest release. Don't set as a pre-release.
- Publish once you're ready to create the release and tag.
- Don't forget the final
-
Add release notes to the release.
- Link to the release announcement in the forum.
📋 Release notes template — expand, fill in links, and paste into the GitHub release
## Release Notes 📢 **[Read the official release announcement on the Forum!](insert-forum-link-here)** We highly recommend checking out the forum post for a user-friendly overview of new features, enhanced with screenshots and guides. --- ### 🛠 Technical Changelogs For a detailed list of technical updates, fixes, and improvements, please review the specific changelogs below: <!-- CHANGELOG section anchors drop dots from the version number: 0.25.0 → #0250 --> * [back-end](https://github.com/getodk/central-backend/blob/master/docs/api.yaml) * [apps/central](https://github.com/getodk/central-frontend/tree/master/apps/central/CHANGELOG.md#<version-without-dots>) * [apps/forms](https://github.com/getodk/central-frontend/tree/master/apps/forms/CHANGELOG.md#<version-without-dots>) * [packages/web-forms](https://github.com/getodk/central-frontend/blob/master/packages/web-forms/CHANGELOG.md#<version-without-dots>) * [packages/xforms-engine](https://github.com/getodk/central-frontend/blob/master/packages/xforms-engine/CHANGELOG.md#<version-without-dots>) * [packages/xpath](https://github.com/getodk/central-frontend/tree/master/packages/xpath/CHANGELOG.md#<version-without-dots>) * [Operations infrastructure](https://github.com/getodk/central/blob/master/CHANGELOG.md#<version-without-dots>)
Update API docs
- Update the API docs in the
docsrepository. Using a new branch in your fork of thedocsrepository, copycentral-backend/docs/api.yamltodocs/docs/_static/api-spec/central.yaml. Create a new PR for the branch. - 🔎 Review the PR.
- Merge any other relevant docs PRs.
- Check future release PRs. When you merge one of these, remove the
future releaselabel.
Announce the release
- Move the forum topic from the Scheduled category to the Releases category.
Update news
- Create a new PR to update
central/docs/news.html, branching off themasterbranch.- Link to the forum post. Limit the number of news items to 2. Target the
masterbranch.
- Link to the forum post. Limit the number of news items to 2. Target the
- 🔎 Review the PR. Feel free to "Squash and merge" when you merge.
Update the next branch
Do this once the news PR has been merged.
- Reset the
nextbranch to the tip of themasterbranch. Themasterbranch will be ahead of thenextbranch, so this doesn't require a force-push.
Metadata
Metadata
Assignees
Labels
No labels
Type
Projects
- StatusShow more project fields✅ done
Activity
matthew-white commentedon Sep 10, 2026
v2026.3.0 🚀
https://forum.getodk.org/t/58502
#2221
garethbowen commentedon Sep 10, 2026
Web Forms features for the forum post are documented here: https://forum.getodk.org/t/odk-web-forms-v1-1-0-beta-one-question-per-page-set-values-in-url-and-last-saved/58508
I think it would make sense to copy those into the release forum post.
matthew-white commentedon Sep 10, 2026
I don't think I have edit access to the forum post, but I'll let Nicole know. 👍
matthew-white commentedon Sep 11, 2026
I've updated the release notes template above to include the changes from #2226. It will now link to the new changelog for operations infrastructure.
matthew-white commentedon Sep 11, 2026
Done in getodk/central-frontend#1899.
sadiqkhoja commentedon Sep 11, 2026
Created getodk/docs#2104 for API docs
sadiqkhoja commentedon Sep 11, 2026
Draft release for central-backend created: https://github.com/getodk/central-backend/releases/tag/untagged-d9a09b6879ef70b3a094
matthew-white commentedon Sep 11, 2026
Mostly the publish step seemed to be successful. However, per-package tags were not pushed. I've filed #2230 about that. I don't think these tags are critical, in that they don't drive ODK ops. Given that, I think we can proceed with the release.
matthew-white commentedon Sep 11, 2026
I've verified that there are new packages on npm for:
web-forms,xforms-engine, andxpath. That matches the packages that changed in getodk/central-frontend#1899. packages/common also changed, but I'm pretty sure we don't publish that. I'll try to remember to update the changelog to mention that packages/common is expected not to be on npm.matthew-white commentedon Sep 12, 2026
The release is out, so I'm going to go ahead and close this out. 🚀