App Development Best Practices-2 (Version control extended)

In the previous article of this series, we saw how to set up a version control system git. In this article, we will enhance it a bit more.

While we are now able to record the changes of our app development, a few more enhancements will help us with

  1. Providing some structure to our work

Conventional commit is one such tool that helps us to achieve the above. In conventional commit, we compose the git commit message in a specific format.

<type>[optional scope]: <description>

[optional body]

[optional footer]

Ref: https://www.conventionalcommits.org/en/v1.0.0-beta.4/#summary

Some example commits with this format are

feat: login with email, passwordISSUES CLOSED: https://agenthunt.atlassian.net/browse/MB-1feat: signup with emailISSUES CLOSED: https://agenthunt.atlassian.net/browse/MB-2docs: add contribution guidelines documentationISSUES CLOSED: https://agenthunt.atlassian.net/browse/MB-6

There are derived benefits of following this structure. Conventional commit ties nicely to a versioning system called SemVer.

SemVer is primarily used for APIs and many might argue that it doesn't make sense for apps (An earlier version of me was in that club who has had major version upgrade 😀), an interpretation of SemVer can be applied.

From the SemVer site

Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make incompatible API 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.

My interpretation of SemVer for apps is

Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make significant changes to UX of the app,
MINOR version when you add functionality, and
PATCH version when you make bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

feat type is used to feature development. It results in minor version increment

fix type is used to fix bugs. It results in patch version increment

feat and fix are the main types that is relevant to product owners/managers/customers.

Additionally there can be optional types such as docs , ci , test or anything that helps structure the work and easier to read git history mainly for developers.

Humans are not very good at following checklists . That is why we created tools that helps us to keep in check :)

Let us add a tool in the form of a GitHub Action called Conventional Commit Checker that will help us automatically check for this format. Create a .github/workflows/main.yaml file with following contents

name: CIon:
pull_request:
branches: [master]
types: [opened, edited, synchronize]
jobs:
check-for-cc:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: check-for-cc
id: check-for-cc
uses: agenthunt/conventional-commit-checker-action@v1.0.0

You would also need to enable branch protection rules for your target branch. This will run the action whenever a Pull Request is opened, edited or synchronized. The PR title is validated for conventional commit title format. The PR description(first comment) is validated for conventional commit body and footer format. If you need to override the check for example, make sure there is a JIRA ID always in the footer, we can modify as below

name: CIon:
pull_request:
branches: [master]
types: [opened, edited, synchronize]
jobs:
check-for-cc:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: check-for-cc
id: check-for-cc
uses: agenthunt/conventional-commit-checker-action@v1.0.0
with:
pr-body-regex: '(.*\n)+(ISSUES RESOLVED: https://agenthunt.atlassian.net/browse/MB-(\d)*)'

One limitation with GitHub Action is that when you press Squash and merge Button, the default description is the combined commit messages of all individual commits in the PR.

To benefit from this GitHub Action as of now, you need to manually copy and replace the default description with PRs first comment.

So now, we have a way to comply with the conventional commit format. You can find the repo changes at https://github.com/agenthunt/mitt-butik

We also get some added benefits which I will summarise below from conventional commit website as is . We will also see in future articles on how to derive these benefits.

Automatically generating CHANGELOGs.
Automatically determining a semantic version bump (based on the types of commits landed).
Communicating the nature of changes to teammates, the public, and other stakeholders.
Triggering build and publish processes.
Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
Ref: https://www.conventionalcommits.org/en/v1.0.0-beta.4/#why-use-conventional-commits

Solving Problems. Making Software Better. Intrigued by Elegant Solutions. https://twitter.com/agent_hunt

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store