Git etiquette

It is recommended to follow a system to standardize the commit messages loosely. Following up from commit messages discussed on , the format below is recommended for commit messages:

Code formatting

BALSAMIC is using Black ( as code formatter.

Conventional commits and PRs

PRs should follow the following keywords in the title:

Commit messages are recommended to following the following similar to PRs:

  1. feat: Introducing a new features. This includes but not limited to workflows, SnakeMake rule, cli, and plugins. In other words, anything that is new and fundamental change will also go here. Enhancements and optimizations will go into refactor.

  2. fix: This is essentially a patch. Included but not limited to: bug fixes, hotfixes, and any patch to address a known issue.

  3. doc: Any changes to the documentation are part of doc subject line, included but not limited to docstrings, cli-help, readme, tutorial, documentation, CHANGELOG, and addition of ipython/jupyter notebook in the form of tutorial.

  4. test: Any changes to the tests are part of test subject line. This includes adding, removing or updating of the following: unittests, validation/verification dataset, and test related configs.

  5. refactor: Refactoring refers to a rather broad term. Any style changes, code enhancement, and analysis optimization.

  6. version: Any changes to .bumpversion config and or change of version will be specified with this. This includes comments within .bumpversion, structure of .bumpversion, etc.


Scope is specified within parenthesis. It show the scope of the subject line. The following scope are valid:

  • cli

  • style

  • rule (refers to SnakeMake rules)

  • workflow (refer to SnakeMake workflows)

  • config (refers to configs that are either used or generated by BALSAMIC)

  • Relevant scopes that might fit into a scope description

Note: If scope is broad or matching with multiple (it shouldn’t, but if it does) one can leave out the scope.


It’s better to start Git commit message with the following words:

  • added

  • removed

  • updated