Future application versions

[varl]

App version and release process

Background

Historically all core applications have been bundled with a DHIS2 version, and a separate branch has been maintained per version of DHIS2. So for 2.30 there is a corresponding branch in each application repo.

As we continue to lean into feature toggling applications that can enabled/disable functionality based on the DHIS2 version they are interacting with one version of an app is no longer bound to a single version of DHIS2 and does not need a corresponding branch for the DHIS2 version.

The work on feature toggling is closely related to the overarching goal of decoupling the frontend and backend of DHIS2. This has consequences for the development and release process, notably, on application versioning.

Since our application versions have no practical impact on anything, they have been unattended to, and range between 0.x.x and 37.x.x. This means that it will be non-trivial to use any versions from that range as we would need to clean up hundreds of branches and hundreds of tags across dozens of repos, and even then, it is unknown if our d2 utils release process is going to work correctly and do the expected thing.

Proposal for application versions

Bump all core applications versions to 100.0.0 and follow semver for major, minor, patch with the following definitions:

• major: For when there are breaking changes, for example, when we change DHIS2 version compatibility.
• minor: For new features and capabilities.
• patch: Used for e.g.: bug fixes, translations, dependency version bumps, ...

The main rationale is:

• 100.x provides a large enough jump to imply a significant difference in approach to versioning.
• Bumping to three digits for the major position avoids pattern matching problems for ##.x.x that we use in GitHub, release scripts, etc.
• While not as aesthetic as 1.0.0, it is a pragmatic approach that will work with our current tooling.

Required steps

For each application:

1. (Manual) Build and Upload current version of the application to App Hub.
   • Ensure that minDHIS2Version is set correctly in manifest before building the app, and the version in package.json is set to 99.9.9.
   • If you don't have permission to add the app, then ask someone in platform team to do it.
   • Make note of the App Hub ID that will be generated after uploading the app.
2. Prepare the app for continuous release, this should be similar to this PR
   • The PR should bump the version in package.json to 99.9.9
   • Add missing GitHub workflow actions to dhis2-verify-app.yml. This makes use of an organisation secret DHIS2_BOT_APP_HUB_TOKEN which is available across our GitHub organisation.
   • Update d2.config with App Hub ID from the first step
3. Create and push a Git tag for the last commit : git tag v99.9.9 commit_hash_for_last_commit and git push origin v99.9.9.
4. Create a commit with a BREAKING CHANGE message (this can be an empty commit).
   • the format of the commit message needs to be BREAKING CHANGE: Message - the colon and message are important for semantic-release to trigger a major version bump
   • Open a PR for the commit, and merge it to the main branch. Once merged, semantic-release will bump the major version from 99.0.0 to 100.0.0, and publishes version 100.0.0 to App Hub.

Follow-ups

• This will impact the DHIS2 release process, as we will probably not want to create e.g. DHIS2 related version branches in our application repos.
• This will impact the apps-to-bundle.json references in dhis2-core.
• This will impact the development process, especially Jira, as application versions will not be tied to DHIS2 Core versions, and be decoupled from the DHIS2 release cycle on a per-app basis.
• What do we do about "branch new" applications ? Do we start them on 1.0.0 or 100.0.0 ?
• If the Optional step about d2 utils release was not done beforehand, it needs to be followed up.

Release flow

Workflow changes

• master branch is now the stable release branch.
• Use a develop branch for on-going development if it's not possible to finalize a feature branch from a QA perspective before merging to master.
• 100.x is a maintenance branch for minor versions under the major version, same applies for 101.x, and so on.
• 100.x.x is a maintenance branch for patch versions under a minor version, same applies for 100.1.x, 101.2.x, and so on.
• alpha, beta are reserved for pre-release branches.
• next and next-major can be used to release a next and/or next major version alongside the current stable from master.
• Only use merge (git merge) commits to move code from one release branch to another.

Links

• Feature toggling applications in dhis2-core
• Feature toggling apps in the release scripts

[varl]

Migrated applications

• chore(release): migrate to new app version scheme app-management-app#265
• chore(release): cut v100 and become continuously delivered approval-app#118
• chore(release): migrate to new app version scheme cache-cleaner-app#505
• chore(release): migrate to new app version scheme capture-app#2566
• chore(release): migrate to new app version scheme dashboard-app#2074
• data-administration-app
• data-visualizer-app
• data-quality-app
• datastore-app
• event-reports-app
• event-charts-app
• import-export-app
• interpretation-app
• line-listing-app
• maintenance-app
• maps-app
• menu-management-app
• chore(release): migrate to new app version scheme messaging-app#401
• pivot-tables-app
• chore(release): migrate to new app version scheme reports-app#306
• chore(release): migrate to new app version scheme scheduler-app#323
• chore(release): migrate to new app version scheme sms-configuration-app#340
• settings-app
• tracker-capture-app
• translations-app
• chore(release): migrate to new app version scheme usage-analytics-app#482
• user-app
• user-profile-app

[varl]

Script that automatically (more or less) does the conversion to CD: https://github.com/varl/scripts/blob/master/release-100