Workflow for Git/Github/Release

A proposal for the workflow of how to mange the code base, test it and release to prod

The Goal

  • Define a workflow to handle developing multi-features at the same time, parallelly.

  • A workflow and tool to deliver the code to users: to give it to tester, end user, partial end user for early trying.

    • For those parallelly feature, we should find a way to easily deploy it to dev, and test, prod version without impact the current main version (master)

  • A workflow to handle legacy, maintenance version.

    • When newer version release, it is possible we need to maintain some older version, so we need to find a solution to deploy the old version, fix bugs and so on.

The Solution

We already used semantic release, Github Action, and k8s, we don't need to introduce any new thing, just need to define a specification on steps for development and release.

Prerequisites

  • Install and setup semantic release: https://github.com/semantic-release/semantic-release (We have almost done that for all repos)

  • Set `main` or `master` branch as the default branch, take it as the current production version. (Basically this is our case for all repos)

  • Set up the Github Action to deploy the code to dev/test/prod. (Currently we have done it for all apps/services)

  • Besides the prod release channel, prepare two release channel for `beta` and `alpha` lease channel, it could be a domain (alpha-admin.treetracker.org, alpha-web.treetracker.org) and corresponding s3 bucket or a router (https://prod-k8s.treetracker.org/alpha/wallet/)

Workflow for Developing Multi-feature

To deploy a new feature, say, customizable web map (CWM), so the goal is that we want to develop this feature on a dedicated branch, and deploy it to the alpha channel on our dev/test/prod env, so our user can test, use it on that channel, say, alpha-web.treetracer.org for prod, and https://dev-k8s.treetracker.org/alpha/webmap/ for dev env, https://test-k8s.treetracker.org/alpha/webmap/ for test env.

  1. Assuming current version on `main` is 1.1.1

  2. Create branch `cwm`, set semantic release (.releaserc config file) as below:

    {
  "branches": [
    '+([0-9])?(.{+([0-9]),x}).x',
    'master',
    'next',
    'next-major',
    { name: 'cwm', channel: 'alpha', prerelease: true },
  ],
    "plugins": [
      ...
    ]
}

    By this setting, semantic release will take the `cwm` as a releasable version and deploy it to dev env when code merged to `cwm`, and deploy to test and prod when some Github Action is executed manually.

  3. Develop and push to `cwm` will trigger the release:

    1. Calculate the version according to the commit comment (feat, fix), and attach the pre-release, for example: 1.2.0-cwm.1

    2. Following push will not change the version (1.2.0) but increase the number after cwm (e.g. 1.2.0-cwm.2)

  4. We can manually run Github Action to release 1.2.0-cwm.2 to test and prod env on the `alpha` channel (alpha-map.treetracker.org)

  5. When the feature is finished and we are ready to normally release it, merge the `cwm` to `main`, this will trigger semantic release to calculate the version and do a release to dev env.

    Say, at this moment, the `main` 's version is 1.3.1, the semantic release will consider the commits from the `cwm` and get the final version, say, 1.4.0

  6. New version 1.4.0 with this new feature was ready, can can be release to prod default channel (map.treetracker.org)

Some other consideration/scenarios:

  • We should frequently merge the `main` to `cwm` to avoid big conflicts at the final merge, and sync the newest feature/code from master to `cwm`.

  • Because release channel requires resources, for example, domain, so we just set two channel, beta, alpha, so at the same time, for one channel, there only is one active branch that could be used/visited. It is possible there are more than 1 branch that are set in the config as `beta`, but the beta channel will be the code of the branch that was deployed most recently.

Workflow for maintaining legacy version

We need to maintain a specific version for some reason, for example, the micro-service developed version v1 and v2, we can not directly remove v1 when we release v2, we need to give the clients time to upgrade to v2.

Assuming we want to upgrade the wallet api from v1 to v2, the API for v1 is deployed to https://prod-k8s.treetracker.org/wallet/ and v2 is about to deploy to https://prod-k8s.treetracker.org/wallet/v2, currently, the semantic release setting is (.releaserc)

{
  "branches": [
    '+([0-9])?(.{+([0-9]),x}).x',
    'main',
    'next',
    'next-major',
  ],
    "plugins": [
      ...
    ]
}

The code for v2 is in branch `v2`.

Now, to release the v2, and switch v1 to maintenance:

  1. Say, the current `main` version is 1.10.0, now create branch `1.x` from `main` branch.

  2. Change the release setting to:

    {
  "branches": [
    {name: '1.x', range: '1.x', channel: '1.x'},
    'main',
    'next',
    'next-major',
  ],
    "plugins": [
      ...
    ]
}

    So the branch `1.x` will be taken as maintenance branch, and deployed to 1.x channel. So we need to change the development respecting the 1.x channel to point to https://prod-k8s.treetracker.org/wallet/ (the current online url) and we also need to change the default deployment to https://prod-k8s.treetracker.org/wallet/v2, so the `main` branch will be deployed to that url.

  3. Merge the branch for v2 to `main` branch, then the semantic release will calculate the version number, say, 2.0.0, and deploy the code to default channel, according to the change above, it would be https://prod-k8s.treetracker.org/wallet/v2.

  4. The following push on `main` will increate the version number, say, 2.1.0 and deploy to https://prod-k8s.treetracker.org/wallet/v2 continuously.

  5. If we want to fix a bug on 1.10.0:

    1. Push a commit with comment: `fix: a bug` to `1.x`

    2. Get the new version number: 1.10.1

    3. Deploy 1.10.1 to 1.x channel: https://prod-k8s.treetracker.org/wallet/

  6. If we want to add a feature on 1.x:

    1. Push a commit with comment: `feat: a feature` to `1.x`

    2. Get the new version number: 1.11

    3. Deploy 1.11 to https://prod-k8s.treetracker.org/wallet/

  7. If we accidentally add a break change on 1.x:

    1. Push a commit with comment: `... BREAKING CHANGE`

    2. Semantic release will throw an error and deny to generate new release.

    3. CAN NOT deploy 2.0.0 (according the rule of SR) to `1.x` channel.

So in this way, we can evolve new version on the branch `main` and maintain the version 1.x at the same time.

Some other consideration or scenarios:

  • If we fixed a bug on `main` and now we also want to adapt it in the `1.x` because the bug is also impact the 1.x version, and the opposite operation is also possible (to adopt change from 1.x to main)

    1. Cherry-pic the commit from the source to target.

    2. Semantic release calculate the version.

    3. Deployment

PreviousPage 1

Last updated