Git workflow for code, API specifications and tests

Exposed API versions

The exposed API versions is the API specifications MAJOR versions, and ALWAYS pointing to its latest MINOR.PATCH.

API specification MINOR versions MUST always be MAJOR compatible.
If a change to the API, micro service or back end is not backwards compatible the API specification MAJOR version MUST increase.

Semantic Versioning 2.0.0

When you update the API specification version use the "MAJOR.MINOR.PATCH".

When you only update the micro service back end, create a new release candidate tag.

Conventional Commits

"feat!: Breaking backward compatible change"
"feat: What backward compatible change was added"
"fix: What bug/defect was fix or performance improvement was patched"

"feat!.feat.fix" maps to "MAJOR.MINOR.PATCH"

Other commit types:

refactor: and perf: can be mapped to PATCH.

Use commit message with ! to draw attention to breaking change.

Trunk-Based Development

You can either do a direct to trunk commit/push (v small teams) or a Pull-Request workflow as long as those feature branches are short-lived and the product of a single person.

If you have more than a couple of developers on the project, you are going to need to hook up a build server to verify that their commits have not broken the build after they land in the trunk, and also when they are ready to be merged back into the trunk from a short-lived feature branch.

Deploy to test

When you make a new commit or merge to main branch create a new release candidate tag.
Deploy release candidates tag to a local, test or staging environment that you can run tests on.

Testing

Setup contract testing to detect if there is a difference between the specification and the API implementation.

If you find a bug in the implementation fix it and at minimum increase the release candidate number.

If you find a bug in the specification fix it and increase at minimum the patch number.