Skip to Content
IntroductionSource ControlConventions

Conventions

Certain conventions we follow to maintain consistency and clarity across our monorepo's git history.

In our source control practices, we adhere to specific conventions to ensure clarity, consistency, and effective collaboration among our development team. These conventions encompass frequent commits, branch naming standards, and structured commit messages.

Frequent Commits

We encourage frequent and meaningful commits throughout the development process. This approach promotes granular tracking of changes, simplifies debugging, and facilitates collaboration among team members.

Changelogs

Changelogs are automatically generated from commit messages so it’s important to follow the conventions outlined below when writing commit messages.

Branch Naming

Branch Categories

When creating branches, we follow a structured naming convention that begins with a category word, indicating the type of task or work being addressed by the branch. Here are some of the most commonly used category words:

  • feature: Signifies the development of a new feature.
  • bugfix: Indicates a branch focused on fixing a bug.
  • hotfix: Reserved for addressing critical hotfixes.
  • test: Used when adding, removing, or modifying tests.
  • wip: Denotes branches that are work in progress and not yet completed.

Branch Name Format

The format for branch names follows the pattern {category}/{issue_id}-short-title. The inclusion of the issue id in the branch name is crucial for linking the branch to the corresponding task in our Jira issue tracking system.

Here are some sample branch names:

feature/PUF-468-new-build-system
bugfix/UIP-469-fix-build-error
hotfix/UIP-470-fix-acc-deployment
test/UIP-471-add-unit-tests
wip/UIP-472-add-new-feature

Even if you’re not actively working on an issue, you can create a branch without an issue id for ongoing tasks or exploratory work.

Commit Messages

We follow the conventional commit message format specified by @commitlint/config-conventional. This format ensures that commit messages are structured and meaningful. Below are examples of commit messages in the context of our project:

feat(auth): [PUF-468] Add authentication module
fix(ui): [UIP-469] Resolve UI rendering issue
chore(ci): [UIP-470] Update build configuration
test(ci): [UIP-471] Enhance unit tests coverage
docs(root): [UIP-472] Update project documentation

Example Commitlint config

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'scope-enum': [
      2,
      'always',
      ['ui-kit', 'ui-protocol', 'cli', 'docs', 'storybook', 'root']
    ],
    'subject-max-length': [2, 'always', 100],
    'scope-empty': [2, 'never']
  }
};

Using this format allows us to automatically generate changelogs and understand the purpose of each commit at a glance.

WorkflowReleases