Skip to content

Latest commit

 

History

History
235 lines (159 loc) · 13.5 KB

VERSIONING_RELEASE.md

File metadata and controls

235 lines (159 loc) · 13.5 KB
Raw

Versioning and Release

Introduction

Each piece of software must have a version that can be found as a TAG in git repository and as Docker Image TAG (if the software is dockerized).

There are two categories of softwares:

  1. Pure services; services without data integration dependencies (e.g. service-stac, service-wmts, service-qrcode, ...)
  2. Data services; services tightly coupled with data integration (e.g. config-wms-mapfile, service-search-sphinx, mf-chsdi3, ...)

These two categories use different versioning scheme

  1. Pure services => SemVer 2.0 version
  2. Data services => Milestone version

SemVer 2.0

Specification: SemVer 2.0

Code that is not tightly coupled with data integration process uses SemVer 2.0 versioning.

SemVer was initially developed for API versioning but proved to be useful for applications as well. Quoting the summary of SemVer:

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API (or software) changes,
  • MINOR version when you add functionality in a backwards compatible manner, and
  • PATCH version when you make backwards compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

We use the SemVer with the v prefix; vMAJOR.MINOR.PATCH

The git repository tagging and release is automated via github actions (see .github/workflows/semver-release.yml). It should be noted explicitly that this action doesn't change the git history, i.e. it doesn't modify files (e.g. a version file) or add annotated tags.

See also Setting up SemVer Workflow.

New SemVer Beta Version

Beta versions are automatically done on every push to develop. A beta version as the following form; NEXT_VERSION-beta.X where NEXT_VERSION is the next semVer version (last version with MINOR incremented by one, e.g. v1.2.0) and X an incremental number.

New SemVer Release

New version are done on demand by creating a PR from develop into master. The PR title should be set to one of the following bump types:

  • #major to increment the MAJOR version (for breaking changes version)
  • #minor to increment the MINOR version (default behavior)
  • #patch to increment the PATCH version (for hotfix)

Once the PR is opened, a github action automatically set the title to New Release <next-version> - <bump>.

NOTE: If the bump type is not set in the original title, then by default it will be set to minor. If any commit(s) since last release contains a bump type, then the higher bump type has precedence. For example if a previous commit contained the #major bump type and the #minor bump type is set to the New Release PR, then #major takes precedence.

The PR should be reviewed by at least one person before merging.

When the PR is merged, a github action generate a new git TAG version (based on the bump type).

After tagging a new Github Release with Release Note is generated by the action. See Release Notes

Hotfix Release

Hotfix Release are created by creating a PR to merge hotfix-* branch directly into master. The PR title should reflect the changes. Optionally the PR title can contain one of the following bump type pragma:

  • #patch to increment the PATCH version (hotfix default behavior)
  • #minor to increment the MINOR version (if the hotfix requires more a minor changes as a simple patch)
  • #major to increment the MAJOR version ! SHOULD NEVER BE DONE IN HOTFIX !

Once the PR has been opened, a github action automatically updates the PR title to <original-title> - <bump-type> where bump-type is automatically set based on the branch prefix:

  • #patch -> for hotfix-* or bug-*
  • #minor -> for feat-* or feature-*

The title can then still be manually updated if needed and the manual bump type pragma takes precedence to auto pragma from branch name.

Then the PR needs to be reviewed and merged.

When the PR is merged, a github action generates a new git TAG version (based on the bump type).

After tagging a new Github Release with Release Note is also generated by the action. See Release Notes

Once all hotfixes have been done, we need to merge back master into develop in order to back port the changes. See Merging master into develop or develop-YYYY-MM-DD for solving conflicts.

NOTE: alternatively we considered using git cherry-pick instead of merging, which keeps a cleaner git history. However this often results in merge conflicts during the next release. To avoid such conflicts or to have the conflicts as soon as possible (which is easier to resolve sooner than later) we use the merge strategy over cherry-pick

Milestone version

For code that is tightly coupled with data integration, a versioning scheme based on a scheduled milestone makes more sense as the code is released with a defined cycle (currently every two months).

See also Setting up Milestone Workflow.

Goal

The goal is to have accross all repositories and docker images the same tagging for a milestone that we can easily identify. The processes and tagging should be as much as possible automated via github actions triggered by PR.

Definition

A Milestone is defined by a date (scheduled deploy date) in the following format:

YYYY-MM-DD

Each repository that follows this scheme MUST have a milestone defined as above and all PR related to this milestone should be attached to it.

Each milestone release (git repository state that is used for deployment) must have a git tag on master branch as follow

YYYY-MM-DD-rcX

with X being an incremental number starting from 1 and where YYYY-MM-DD refers to the corresponding milestone (could defer from the date of the tag creation). This git tag is automated via github action when the a PR is merged into master (see .github/workflows/milestone-release.yml).

For services that uses docker images, all milestone images are tagged with the same git tag; YYYY-MM-DD-rcX. For docker image built during the milestone (PR merged in the develop-YYYY-MM-DD branch, they are tagged as <branch>.latest (e.g. develop-2022-09-10.latest).

For each git tag on master branch a github Release is automatically generated via github action (.github/workflows/milestone-release.yml). This Release contains Release Notes automatically generated from the milestone PRs.

Milestone Workflow

  1. In the beginning of the milestone, a developer creates the milestone branch develop-YYYY-MM-DD on the repository based on top of master (can be done directly within github web interface or from CLI). The branch creation trigger the following github workflow:

    • create-milestone.yml this workflow does then the following actions
      • Get the milestone name from the branch name; develop-YYYY-MM-DD => YYYY-MM-DD
      • Create or re-open github milestone YYYY-MM-DD
      • Set the github default branch to the next milestone branch develop-YYYY-MM-DD. (NOTE: this really set to the next milestone branch, so if you create the overnext milestone branch, the default branch stays on the next milestone branch and not the overnext)
      • Set milestone github branch protection. This branch protection is as follow:
        • Require at least one approval review
        • Require CI status check to pass and branch to be up to date
        • Don't allow force push
        • Don't allow branch deletion
        • Enforce all configured restrictions for administrators too
    # Create the milestone branch from CLI
git checkout master
git pull # get latest state of master
git branch develop-YYYY-MM-DD
git push origin develop-YYYY-MM-DD

  2. The developer creates a branch using the correct naming convention based on top of the milestone branch develop-YYYY-MM-DD.

    git checkout develop-YYYY-MM-DD
git pull # get the latest state of milestone branch
git checkout -b data-PB-9999-layer-A

  3. Once the work is done and ready for review, the developer opens a PR to merge his changes into develop-YYYY-MM-DD. Opening a PR trigger the following workflows:

    • pr-auto-milestone.yml. This workflow does the following actions:

    The PR label is used later on to categorize the Release Notes.

    The PR title must be set accordingly to the rules in Pull Request Rules as it will be used in the Release Notes.

  4. If the PR don't require any Release Note (e.g. code cleanup, typo fix, ...), then set the following label to the PR; skip-release-note

  5. Once the PR has been reviewed it is merged and closed.

Milestone release

Once all work for a milestone has been done (this can be checked using the github milestone view, e.g. geoadmin/mf-chsdi3/milestones), a new Release can be created like follow:

  1. Create a PR to merge develop-YYYY-MM-DD into master (note the PR title will be automatically set, so you can give any dummy title during creation). The PR creation/edit/update trigger the following workflow:

    • pr-auto-milestone.yml, which does the following actions
      • Add the PR to the correct github milestone (based on the head branch name develop-YYYY-MM-DD)
      • Set the PR label to new-release
      • Check that all milestone PRs (except this one) are closed. This will prevent to merge this PR as long as there are open milestone PRs.
      • Set PR title to the new release, e.g. : New Release 2022-06-29-rc1

  2. Review the changes (quick review to make sure that everything is included).

  3. Merge the PR. This trigger the following workflow

    • milestone-version.yml with the following actions
      • Tag the repository with YYYY-MM-DD-rcX. With X being 1 or incremented if the tag already exists.
      • Generate github Release with Release Note based on the git tag.
      • Close the github Milestone
      • Delete the milestone branch protection
      • Delete the milestone branch
      • Set the default github branch either to the next milestone branch if it already exists otherwise to master

  4. The Release Notes of the release must be reviewed and edited if needed.

Milestone hotfix

  1. Create a personal branch on top of master following the naming convention.
  2. Do the work
  3. Open a PR to merge the work into master. This trigger github action to add the correct label to the PR.
  4. Once the PR has been reviewed, and merged a github action is triggered to tag the repo with YYYY-MM-DD-rcX with X being incremented based on the last milestone tag. A github release is then also generated with Release Notes.
  5. When all milestone hotfix have been done, merge back master into develop-YYYY-MM-DD in order to update this latest branch. See Merging master into develop or develop-YYYY-MM-DD for solving conflicts.

Release Notes

Release notes are automated by github action and written in the description of the github Release. They are taken from the PR title. If the PR title contains a Jira issue number, this number is transformed into a hyperlink to the Jira issue.

EACH DEVELOPER IS RESPONSIBLE to write meaningful concise PR title that can be understood in the Release Notes context. PR REVIEWER(s) SHOULD also review the PR title.

The release notes are categorized based on the PR label(s).

Label Release Note Category
feature Features
bug Bug Fixes
data Data Integration
new-release Ignored, not part of the release notes
skip-release-note Ignored, not part of the release notes

Deployment

The latest status of develop/develop-YYYY-MM-DD (i.e. the most recent 974517877189.dkr.ecr.eu-central-1.amazonaws.com/<service>:latest image) can and should be deployed frequently to DEV staging. It's acceptable to either deploy develop:latest/develop-YYYY-MM-DD:latest on DEV staging or a tagged pre-release.

For INT staging we deploy only tagged pre-releases or releases, for PROD we deploy only releases.