Skip to content
Documentation
April Robots Documentation
Release Docs & Versioning

Release Docs & Versioning

TODO: review by @shinratttensei1

This document outlines our standardized release process using GitFlow and GitHub CI/CD for:

  • k8s Cluster with:
    • Online App
    • MongoDB
  • Robot Microservice ( DOES NOT need staging )
  • Offline app core ( DOES NOT need staging )

Example workflow from developing to release

Online App

Suppose:

  1. You have just merged a new feature to develop
  2. CI/CD is already configured for all branches

Step 1: Merge to staging ( Skip if you are on Robot MS or Offline App core ) 

git checkout staging
git pull origin staging
git merge develop
git push origin staging

CI/CD deploys code to the staging environment.

Step 2: Create a Proper Release Branch 

# From staging
git checkout -b release/1.4.2

Step 3: Merge into main and tag the release 

git checkout main
git pull origin main
git merge release

# Tag the release
git tag -a v1.4.2 -m "Release version 1.4.2"
git push origin main --tags

Production deploy happens here. CI/CD workflow in current repo will handle it (see workflow status in Actions tab)

Offline App

Suppose:

  1. You have just merged a new feature to develop
  2. CI/CD is already configured for all branches

Step 1: Create a Proper Release Branch 

# From develop
git checkout -b release/1.4.2

Then update CHANGELOG.md. See How to make proper app versioning

git add CHANGELOG.md
git commit -m "Update changelog and bump version to 1.4.2"
git push origin release/1.4.2

Step 2: Merge into main and tag the release 

git checkout main
git pull origin main
git merge release

# Tag the release
git tag -a v1.4.2 -m "Release version 1.4.2"
git push origin main --tags

Offline Backend and Frontend are compiled into an app here. CI/CD workflow in current repo will handle it (see workflow status in Actions tab).

To rerun the workflow manually, navigate the workflow and press Run workflow choosing desired source repo.

TODO

For MS, @shinratttensei1 will describe the process here.

How to Ensure Releases Are Valid

All commits must go through following sequence: -> develop -> staging -> release -> main GitHub actions are successful after on each branch. CI pipeline (tests) must pass Staging build has been tested and approved Tag is only created after final approval

Writing changelog.md

This file should include all notable changes for each version of the application. It must follow the Keep a Changelog format.

Each version section should also contain a ### Compatible Offline Versions block that lists:

  • Specific offline app versions (0.2.0, 0.2.2)
  • Or version ranges (0.2.0 - 0.2.4), which will be expanded automatically.

Example:

## [1.0.0] - 2017-06-20

### Compatible offline versions:

- 0.2.0 - 0.2.7
- 0.3.0

### Added

- "Why keep a changelog?" section.
- "Who needs a changelog?" section.
- "How do I make a changelog?" section.

### Changed

- Start using "changelog" over "change log" since it's the common usage.
- Fix phrasing and spelling in German translation.
  ...

Version naming and tags

We follow Semantic Versioning (SemVer):

  • Format: MAJOR.MINOR.PATCH
  • Examples: 1.4.0, 1.4.1, 2.0.0
  • MAJOR version (X.0.0): Increased for breaking changes or incompatible API/database updates.
    • Example: Database schema is changed and old clients will not work with new data.
  • MINOR version (0.X.0): Increased when new features are added in a backward-compatible way.
    • Example: Added a new report export feature to the Offline App; old apps still work.
  • PATCH version (0.0.X): Increased for backward-compatible bug fixes and small improvements.
    • Example: Fixed a typo in a UI element or corrected a minor database entry.

In addition, there is a latest tag that @shinratttensei1 will explain how it works and why. TODO

General Guidelines

  • Bump MAJOR if any change breaks compatibility or requires all deployments to upgrade.
  • Bump MINOR for new features that do not break old functionality.
  • Bump PATCH for fixes, tweaks, or documentation updates.

Examples

Initial Stable Release

  • Scenario: Project is stable and ready for production.
  • Version: 1.0.0

Adding New Features (MINOR)

  • Scenario: Support for a new robot type added in a backward-compatible way.
  • From → To: 1.0.0 → 1.1.0
  • Scenario: User management added to Online App in a backward-compatible way.
  • From → To: 1.1.0 → 1.2.0

Bug Fixes (PATCH)

  • Scenario: File upload bug fixed.
  • From → To: 1.2.0 → 1.2.1
  • Scenario: Fix for sync failure on slow internet.
  • From → To: 1.2.1 → 1.2.2

Breaking Changes (MAJOR)

  • Scenario: Database schema changed, old Offline Apps incompatible.
  • From → To: 1.4.2 → 2.0.0
  • Scenario: Offline and Online App API fully refactored.
  • From → To: 2.0.0 → 3.0.0

Cloud Sync-Specific Examples

  • New mandatory field in children records, migration required: 1.4.0 → 2.0.0 (MAJOR)
  • New optional field in actions, old Offline Apps can ignore: 1.4.0 → 1.5.0 (MINOR)
  • Something not affecting cloud sync compatibility: 1.5.0 → 1.5.1 (PATCH)

Docker Image Tags:

TODO: Why is this provided in this documentation?

ghcr.io/org-name/image-name:1.4.0
ghcr.io/org-name/image-name:latest (for staging only)

Example on our registry: 

ghcr.io/novators-kz/april-robots-online-general-api:1.4.0
ghcr.io/novators-kz/april-robots-online-general-api:latest

[!NOTE] You can access our packages in (Packages) You need a PAT configured to have packages:write rights (About permissions for GitHub Packages).

CI/CD Workflows

TODO: @shinratttensei1 will rewrite this section to explain the workflows in relevant details and sort out the mess below.

What Is Done by CI/CD vs Manually

CI/CD (Automated):

  • Run tests and linters
  • Build Docker image
  • Push to GitHub Container Registry (ghcr.io)
  • version.json File.
  • Deploy to server
  • Notifications (email/discord)

Manual:

  • Creating release branches
  • Writing release notes
  • QA testing
  • Pushing Git tag (automated for installer compiler)
  • Final approval (by a person who did QA/UAT)

TODO: Release branch workflow for Online App?

When a push is made to a release/{version} branch (e.g. release/1.4.0), the CI workflow will:

  1. Parse the version number from the branch name (1.4.0).
  2. Locate the corresponding section in CHANGELOG.md.
  3. Extract the list of Compatible Offline Versions, supporting both ranges and individual versions.
  4. Generate a machine-readable file named {version}.json (e.g. 1.4.0.json) with the structure shown below.
  5. Save the file to the repository under version_maps/1.4.0.json.
  6. Commit the file to the same release branch with a [skip actions] flag to prevent triggering another CI run.

Example output file: version_maps/1.4.0.json

{
  "version": "1.4.0",
  "compatible_offline_versions": ["0.2.0", "0.2.1", "0.2.2", "...", "0.2.7"],
  "release_date": "2025-07-24"
}

CI/CD Workflow for Version Map Validation and Insertion

1. Step 1: Generate and Validate the version .json File

  • When a file is pushed or updated in the version_maps/ directory, the CI/CD pipeline is triggered.
  • Each release should have its own JSON file named after the version, such as version_maps/1.4.0.json.
  • The pipeline performs two types of checks:
    • Syntax Check:
      Ensures the JSON file is properly formatted and contains no syntax errors.
    • Schema Validation:
      Uses a predefined JSON schema (version_map.schema.json) to verify that all required fields are present, field types are correct, and the overall structure matches project requirements.

2. Step 2: Insert into MongoDB (if Valid and Unique, done by Backend)

  • After the file passes validation, the backend connects to your MongoDB database.
  • It checks the version_maps collection for a document with the same version.
    • If a duplicate exists:
      The pipeline stops and reports an error - no new data is inserted.
    • If the version is unique:
      The new version map is inserted into the version_maps collection.
    sequenceDiagram
   actor Dev as Developer(s)
   participant feature as feature/add-login-page
   participant develop as develop
   participant staging as staging
   participant release as release/x.y.z
   participant main as main
   participant CI as CI/CD
   participant DB as MongoDB
   participant GH as GitHub Releases

   Dev->>+feature: Commit code (new feature/bugfix)
   Dev->>develop: Open Pull Request (PR)
   develop->>Dev: Code review & approve PR
   feature->>develop: Merge PR
   Dev->>feature: Delete the feature branch
   feature->>-feature: Deleted
   develop->>CI: Trigger CI/CD
   CI->>CI: Code testing and linting, image for staging
   CI-->>develop: CI/CD Successful

   Dev->>staging: Open Pull Request (PR)
   staging->>Dev: Code review & approve PR
   develop->>staging: Merge PR
   staging->>CI: Trigger CI/CD
   CI->>CI: App deploy on staging environment
   CI-->>staging: CI/CD Successful
   Dev->>staging: Manual QA & User testing

   Dev->>+release: Create release/x.y.z branch
   Dev->>release: Update CHANGELOG.md, version, etc.
   release->>release: Commit & push release changes (CHANGELOG.md)

   release->>CI: Trigger CI/CD
   CI->>CI: Validate version_map/<version>.json
   CI->>CI: Code testing and linting, image for production
   CI->>release: Commit version  file into the same branch (skipping ci)
   CI-->>release: CI/CD Successful

   Dev->>main: Open Pull Request (PR)\
   main->>Dev: Code review & approve PR
   release->>main: Merge PR
   main->>CI: Trigger CI/CD
   CI->>CI: Image for prod, App deploy on prod
   CI->>DB: Insert version file if unique
   CI-->>main: CI/CD Successful

   Dev->>main: Tag new release
   Dev->>GH: Publish GitHub Release (with release notes)

   Dev->>main: (Optional) Open PR to merge main back to develop
   main->>develop: Merge PR
Database MigrationsRobots Ideal State