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_libmodeller_de_libmodeller_ml_jobmodeller_be_apimodeller_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
masterin 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
patchin semantic versioning. - feat: For a feature-level change, include
featin the commit message. This corresponds to aminorversion 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.pyconfiguration. - 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
In general things related to SCM:
- Do not push large files to Git.
- Do not commit secrets to Git.
- Do not commit directly to protected branches.
- Generate the
.gitignorefile withgitignore.io.