Mastering Versioning and Git Flow: A Practical Guide to Release Management

Concept

Product version is the version defined for a project/sub‑project, formatted as x.y (e.g., 1.2).

Engineering version is the version of the built artifact, usually four segments x.y.z.build. x.y inherits the product version; z is the sprint number (or a serial number in waterfall); build is the build number generated by the build tool.

Test code also has an engineering version; the z.build part is decided by the test team and should be changed for each formal delivery.

Release tag – each production release is marked in the Git repository with a tag whose value is the engineering version (x.y.z.build).

Goal

Unify branch management strategy and definition. Version everything to improve team collaboration efficiency, accelerate new feature development and release management.

Principles

Adopt GitHub Flow (recommended) or trunk‑based development.

Require complete automated testing, CI and deployment infrastructure.

Version everything.

Code review process must exist.

Conditions for automated deployment must be met.

Standards

Code repository

Code must reside in the company‑wide repository.

Repository visibility cannot be public.

Only project‑related developers get permissions, following the principle of least privilege.

Projects must be created in team spaces, not personal spaces.

Suggested team space naming: group/[subgroup] (e.g., gaia/gfs).

Suggested project naming: project‑code‑module[-submodule][-subsubmodule] (e.g., gaia-gfs-demo).

Branch naming (GitHub Flow)

master branch is protected; direct commits are prohibited.

Branch names must have meaningful prefixes: feature/{JIRA‑id}-*, bug/{JIRA‑id}-*, hotfix/{JIRA‑id}-*.

Create a merge request (MR) as soon as the branch is created to describe the idea and record discussion.

Unfinished MRs start with WIP:.

At least one member must approve before merging.

When merging, use --squash or enable “Squash commits when merge request is accepted”.

Version

Tag each production delivery with a release tag and record release notes.

Database should have version numbers; migration scripts must be idempotent (e.g., Flyway, EntityFramework Migrations).

Test cases and test data should also be versioned, either matching the engineering version or having a defined mapping.

Recommended Practices

Version usage scenarios

At the start of an agile sprint, define the first three segments of the sprint version.

When submitting, resolving or closing bugs, fill in the corresponding engineering version in DevOps.

During DevOps build, the first three segments are used and the build number is appended automatically.

When releasing to production, DevOps generates the tag from the engineering version.

If deployment is done only via DevOps, there is no sprint version; DevOps appends a batch number (e.g., 1.2.13) to the product version to trace environments and deployments.

Sample development workflow

1. Create a feature branch from master: git checkout master, git pull, git checkout -b feature/11-add_redis_support, git push --set-upstream origin feature/11-add_redis_support.

2. Develop, commit, and push changes: git add --all, git commit -a -m "move display name to redis", git push.

3. Open an MR in GitLab; if work is incomplete, prefix the title with WIP:.

4. Discuss, modify, and test; merge master into the feature branch regularly: git merge master.

5. When the feature is ready and all CI checks pass, tag the release (e.g., git tag add "1.1.0") and push the tag: git push --tag. Enable “Squash commits when merge request is accepted” and “Delete source branch when merge request is accepted”.

6. Deploy the master branch to production and notify other developers to merge master promptly.