Skip to main content

Naming Conventions

· 6 min read
9h
9h
Just a random guy who loves coding.
Le Kiet
Le Kiet
Software Engineer | Data Scientist

A well-defined Git naming convention enhances collaboration, supports automated versioning, and simplifies project maintenance. This document outlines recommended naming conventions for branches, commits, and tags to facilitate a smooth workflow and compatibility with Semantic Release.

Commit Conventions

0. Scopes​

Backend Scopes (Python, FastAPI)​

  • api: General API-related changes, such as routes or request handling.
    • Example: fix(api): correct token validation issue
  • auth: Authentication and authorization logic.
    • Example: feat(auth): add OAuth2 support
  • llm: LLM-specific logic, including model loading and response generation.
    • Example: perf(llm): optimize LLM response caching
  • database: Database models, migrations, or queries.
    • Example: fix(database): correct migration script for user model
  • schemas: Pydantic or data validation schemas.
    • Example: refactor(schemas): update response schema for LLM results
  • middleware: FastAPI middleware (e.g., CORS, logging).
    • Example: chore(middleware): add logging middleware for request tracing
  • background: Background tasks or scheduled jobs.
    • Example: feat(background): add scheduled job to refresh model
  • config: Configuration files or environment variable updates.
    • Example: chore(config): add env variable for LLM model path
  • testing: Unit and integration tests for backend logic.
    • Example: test(testing): add tests for LLM response accuracy
  • deps: Dependency updates or additions.
    • Example: chore(deps): upgrade FastAPI to latest version

Frontend Scopes (JavaScript, Next.js)​

  • ui: General UI/UX changes, layout adjustments, and styling.
    • Example: style(ui): improve layout for model response view
  • auth: Frontend authentication handling, including login and token management.
    • Example: feat(auth): add persistent session handling
  • api: Frontend API calls or data fetching logic.
    • Example: refactor(api): update request headers for secured endpoint
  • llm-display: UI components specifically for displaying LLM responses.
    • Example: feat(llm-display): add loading spinner for LLM responses
  • forms: Form components for user inputs, especially related to LLM queries.
    • Example: fix(forms): correct validation error messages
  • state: Application state management (e.g., Redux, context API).
    • Example: chore(state): add state management for user settings
  • config: Frontend configuration, environment variables, or Next.js settings.
    • Example: chore(config): add environment variable for API base URL
  • deps: Frontend dependencies and package management.
    • Example: chore(deps): update Next.js to latest version
  • i18n: Localization and language support.
    • Example: feat(i18n): add support for Spanish language
  • testing: Unit or end-to-end tests for frontend components.
    • Example: test(testing): add Jest tests for LLM response UI
  • seo: SEO-related adjustments (e.g., meta tags, titles).
    • Example: chore(seo): update meta description for homepage

Full-Stack or Shared Scopes​

  • docker: Docker configuration and setup.
    • Example: chore(docker): optimize Dockerfile for smaller image size
  • docs: Documentation changes for both backend and frontend.
    • Example: docs(docs): update README with API usage examples
  • env: Environment variables or configuration shared between backend and frontend.
    • Example: chore(env): add new environment variable for model type
  • build: Build scripts or deployment configurations.
    • Example: chore(build): optimize build for production deployment
  • ci: Continuous Integration setup or updates.
    • Example: chore(ci): add automated test for LLM endpoint responses

1. Branch Naming Conventions​

Branch naming conventions help distinguish between different types of work and keep the Git repository organized. Each branch name should reflect its purpose and scope, using a clear and consistent naming pattern.

Primary Branches (Default Branches)​

Primary branches represent key stages of the project lifecycle:

  • main: The main branch contains the latest stable production-ready code.

Feature Branches​

Feature branches are used to work on new features or enhancements in isolation from the main codebase.

Pattern: feat/{issue-id}/{short-description}

Examples:

  • feat/102/add-user-authentication
  • feat/145/improve-dashboard-ui

Guidelines:

  • Issue ID: Include the issue or task ID if using a tracking tool like Jira or GitHub Issues.
  • Short Description: Use a concise description in kebab-case (lowercase, separated by hyphens) to describe the purpose of the feature.

Hotfix and Bugfix Branches​

Hotfix and bugfix branches are used to address issues either in production or development environments.

Hotfix Branches​

Pattern: hotfix/{short-description}

Examples:

  • hotfix/fix-critical-auth-bug
  • hotfix/remove-duplicate-entries

Bugfix Branches​

Pattern: bugfix/{issue-id}/{short-description}

Examples:

  • bugfix/203-correct-profile-picture-upload
  • bugfix/207-fix-login-loop-error

2. Commit Message Conventions​

Using semantic and structured commit messages ensures readability, consistency, and compatibility with Semantic Release tools, enabling automated versioning.

Commit Conventions

Commit Message Structure​

A standard commit message follows this format:

<type>(<scope>): <subject>
  • type: Specifies the type of change (e.g., feat, fix) to indicate its impact on the code.
  • scope: Indicates the module or area affected (optional).
  • subject: A brief, imperative description of the change.

Semantic Commit Types​

The following commit types align with Semantic Versioning, automatically updating version numbers based on the types of changes introduced.

  • feat: A new feature (increases the MINOR version).
  • fix: A bug fix (increases the PATCH version).
  • docs: Documentation changes only.
  • style: Changes in code formatting, not affecting code behavior.
  • refactor: Refactoring code without affecting functionality.
  • test: Adding or modifying tests.
  • perf: Code changes that improve performance.
  • chore: Routine tasks, maintenance, or build changes.
  • build: Changes affecting the build system or dependencies.

Best Practices for Commit Messages​

Examples:

feat(auth): add OAuth2 support for social login
fix(ui): correct layout issue on mobile navbar
docs(readme): update installation instructions

Guidelines:

  • Use the imperative form: (e.g., “fix,” not “fixed”).
  • Keep subjects concise (50 characters or less).
  • Add a body section if further explanation is needed, separated by a blank line after the subject line.
  • Avoid WIP (Work In Progress) commits in the main branches.

3. Tag Naming Conventions​

Tags mark specific points in the project’s history, typically used for release versions. Follow Semantic Versioning format for tagging releases.

Release Tags​

Semantic Release relies on tags for versioning. Tags should be consistent, indicating the major, minor, and patch levels as vMAJOR.MINOR.PATCH.

Pattern: v<MAJOR>.<MINOR>.<PATCH>

Examples:

v1.0.0
v1.2.1
v2.0.0-alpha

Notes:

  • Pre-release tags: Use pre-release identifiers (e.g., alpha, beta) for early versions (e.g., v1.0.0-alpha).
  • Automated Tagging: When using Semantic Release, tags are automatically generated based on commit messages, ensuring consistent versioning.