Naming convention

In our collaborative environment, it's important that we maintain clear, consistent conventions for our work — this includes how we name pull requests (PRs) and branches, and write commit messages in our version control system.

We follow Conventional Commit guidelines for writing commits messages, and as a method to name PRs and branches. This ensures our codebase remains navigable and our workflow smooth. Please follow these guidelines when contributing to our repositories.

Picking a task type

Writing commit messages, and naming branches and PRs requires a <type>, which denotes the type of task to be completed. Here is a list of task types:

  • build 🛠 - changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm);
  • ci ⚙️ - changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs);
  • chore ♻️ - other changes that don't modify src or test files;
  • docs 📚 - documentation only changes;
  • feat ✨ - a new feature;
  • fix 🐛 - a bug fix;
  • perf 🚀 - a code change that improves performance;
  • refactor 📦 - a code change that neither fixes a bug nor adds a feature;
  • revert 🗑 - reverts a previous commit;
  • style 💎 - changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc); and
  • test 🚨 - adding missing tests or correcting existing tests.

Naming branches

Consistent branch naming can simplify the understanding of what work is happening where. Our naming convention for branches is the following: <task-type>/<id>-<description>

  • The <task> denotes the type of task. Refer to the task type list for details.
  • The <id> is the issue id number of a task in a task tracking tool like in Gitea or Jira to help associate the PR with a specific task.
  • The <description> is a concise, yet informative description of the changes. Use hyphens for spaces. For example, update-user-profile.

✅ Good

feat/123-add-user-profile

build/456-switch-to-commitlint

🚫 Bad

alert dialog

fix branch

Writing commit messages

Good commit messages are just as important as good code. They provide context about what and why things have changed, which aids future code archeology. Here's our preferred structure: <type>: <description>

  • The <type> should be the kind of changes included in the commit. Refer to the task type list for details.
  • The <description> should be a brief description of changes, written in the imperative, present tense. For example, "add" not "added", "change" not "changed".

✅ Good

build: fix TypeScript configuration

🚫 Bad

fix build

Naming pull requests

Pull requests (PRs) keep our codebase clean and understandable. The name of a PR should give an overview of the changes included in the PR and should be concise, yet descriptive. The format of a PR should be <type>(optional scope):<description>.

  • The <type> should be the kind of changes included in the commit. Refer to the task type list for details.
  • The optional scope may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis. For example, feat(parser): add ability to parse arrays
  • The <description> should be a brief description of changes, written in the imperative, present tense. For example, "add" not "added", "change" not "changed".

✅ Good

feat(parser): add ability to parse arrays

🚫 Bad

fix branch