SCM conventions & ways of working

When we are working in an collaborative work environment, this is important to share a common set of convention which makes collaboration easier. Here are some of the common gitops best practice which has helped to collaborate better,

Repository naming convention

{short product name}_{component}_{type of repository}

Short product name:

• modeller: modelling engine
• optimizer: optimization engine

Component:

• ui: any code related to the user interface
• ml: anything to do with machine learning code base
• de: anything to do with data engineering code base
• be: anything to do with REST API endpoints for ml, de or in general application.

Type of repository:

• app: mostly used for ui and cli standalone application.
• lib: library code base of ml and de engines.
• job: cli or script based jobs which will be executed in a batch process.
• api: code base related to apis.

Example:

• modeller_ml_lib
• modeller_de_lib
• modeller_ml_job
• modeller_be_api
• modeller_ui_app

Branch naming convention:

Code Flow Branches (restricted commit branch):

develop: developers can merge their branches here. staging: any final tagging or testing has to happen here. master: production branch, if all the validation is working in staging and tested code needs to be merged here. test: other than unit testing regression, integration and end to end testing has to happen here.

Flow of code: develop > test > staging > production

Temporary Branches:

• feature: anything which is a feature has to be developed in a feature branch and the branch name should be like : feature/{name of the feature} [example: feature/integrate-swagger]
• bug fix: any bug fix has to be done in a bud fix branch. the structure remains as feature branch. structure of the branch name will be like bugfix/{bug which is being fixed} [example: bugfix/more-gray-shades-in-loader]
• hot fix: any hotfix from master has to be made in this branch. also, note that these fixes has to be merged in other common branches that the master branch. [example: hotfix/disable-endpoint-zero-day-exploit]
• experimental: any experimental work has to be tagged this way while creating a branch. [example: experimental/dark-theme-support]
• build: any build branch should start with the build pre-fix. [example: build/jacoco-metric]
• release: any release branch has to be tagged by a release prefix. [example: release/myapp-1.01.123]
• merging: any intermediate merge branch has to be tagged with merge prefix. [example: merge/dev_lombok-refactoring]

Commit convention:

We are adding some keyword to the commit messages based on which a semantic versioning tag can be generated. A version tag will look like, v{MAJOR}.{MINOR}.{PATCH}

Here, this is how commit tags are getting translated to semantic versioning numbers, fix --> patch, feat --> minor and BREAKING CHANGE --> major.

Area of work:

• fix: if there is a small change which does not break any of the high level APIs and does not change overall behaviors of a feature that will be consider as fix. this corresponds to the patch in the semantic versioning.
• feat: if there is a feature level change then the commit should have feat tagged along with in. in terms of the semantic versioning this corresponds to the minor version change.
• BREAKING CHANGE: this is a change where multiple modules and high level APIs are getting changed.
• build: These are not linked with semver. any build level changes has to be tagged as build. for example, if we are changing some configuration in setup.py that should be tagged as build commit.
• chore: updating grunt tasks etc; no production code change
• ci: change in any of the github workflow or azure pipeline level changes has to be tagged as ci commit.
• docs: any changes in wiki documentation or library docstring level changes has to be tagged as docs.
• style: if there is any changes in code due to formatting or linting those can be tagged as style change.
• refactor: if some code is being refactored that has to be tagged as refactored commit.
• perf: for profiling a code base use pref tag.
• test: for any commit related to tests can be tagged as test.

Commit structure:

• {area_of_work}: {ticket_id} {One line description of commit}
• [optional] Detailed description of the commit

In general things related to SCM:

• Do not push large files in git.
• Do not pass secrets in git.
• Do not directly commit in no commit branches.
• Generate .gitignore file from gitignore.io.

Reference:

• Conventional Commits Pattern
• Python library version management with GitHub action + commitizen + pre-commit hook
• Conventional commits