SCM conventions & ways of working

When working in a collaborative environment, it is important to share a common set of conventions that make collaboration easier. Here are some common GitOps best practices that help teams collaborate:

Repository naming convention

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

Short product name:

  • modeller: modeling engine
  • optimizer: optimization engine

Component:

  • ui: code related to the user interface
  • ml: code related to the machine-learning codebase
  • de: code related to the data-engineering codebase
  • be: code related to REST API endpoints for ML, data engineering, or the application in general

Type of repository:

  • app: mostly used for standalone UI and CLI applications
  • lib: library code for ML and data-engineering engines
  • job: CLI- or script-based jobs executed in a batch process
  • api: code 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: Final tagging and testing happen here. master: The production branch. Merge code here after it has passed validation and testing in staging. test: Run regression, integration, and end-to-end tests here, in addition to unit tests.

Flow of code: develop > test > staging > production

Temporary Branches:

  • feature: Develop features in a feature branch named feature/{name of the feature} [example: feature/integrate-swagger].
  • bug fix: Any bug fix should be made in a bug-fix branch. Its structure is the same as a feature branch: bugfix/{bug being fixed} [example: bugfix/more-gray-shades-in-loader]
  • hot fix: Make hotfixes from master in a hotfix branch, then merge them into the other shared branches as well [example: hotfix/disable-endpoint-zero-day-exploit].
  • experimental: Use this prefix for experimental work [example: experimental/dark-theme-support].
  • build: Start build branch names with this prefix [example: build/jacoco-metric].
  • release: Use this prefix for release branches [example: release/myapp-1.01.123].
  • merging: Use this prefix for intermediate merge branches [example: merge/dev_lombok-refactoring].

Commit convention:

We add keywords to commit messages so that semantic-version tags can be generated. A version tag looks like v{MAJOR}.{MINOR}.{PATCH}.

Commit tags map to semantic versioning increments as follows: fix --> patch, feat --> minor, and BREAKING CHANGE --> major.

Area of work:

  • fix: A small change that does not break any high-level APIs or change a feature’s overall behavior is considered a fix. This corresponds to a patch in semantic versioning.
  • feat: For a feature-level change, include feat in the commit message. This corresponds to a minor version change in semantic versioning.
  • BREAKING CHANGE: Use this for a change that affects multiple modules or high-level APIs.
  • build: Use this for build-related changes that are not tied to semantic versioning, such as changes to setup.py configuration.
  • chore: Use this for maintenance tasks, such as updating Grunt tasks, that do not change production code.
  • ci: Use this for changes to GitHub workflows or Azure Pipelines.
  • docs: Use this for changes to documentation or library docstrings.
  • style: Use this for formatting or linting changes.
  • refactor: Use this for code restructuring that does not change behavior.
  • perf: Use this tag for performance-related changes.
  • test: Use this for changes related to tests.

Commit structure:

  • {area_of_work}: {ticket_id} {One line description of commit}
  • [optional] A detailed description of the commit
  • Do not push large files to Git.
  • Do not commit secrets to Git.
  • Do not commit directly to protected branches.
  • Generate the .gitignore file with gitignore.io.

Reference:

Aritra Biswas
Aritra Biswas
Senior Manager, AI Engineering

I work at the intersection of analytics, machine learning, and software engineering, with research interests in computational statistics, causal inference, simulation, and mathematical optimization.