Copy page

Microservices

Version Control & Release Process

Version Control & Release Process

Relevant source files

The following files were used as context for generating this wiki page:

• .githooks/pre-commit
• docs/gitflow.md

This page outlines the version control standards and the release lifecycle for the Primebrick v3 Microservices repository. The project strictly adheres to a GitFlow branching model and utilizes githooks to ensure version consistency across the workspace.

GitFlow Overview

The repository utilizes the GitFlow model to manage parallel development, feature isolation, and production stability. All development work must occur within dedicated branches; direct commits to the primary branches (develop or main) are strictly prohibited docs/gitflow.md:18-18.

Core Branches

• main: Reflects the production-ready state.
• develop: The integration branch for features.
• feature/*: Used for developing new features or tasks. Branches are branched from develop and merged back into develop using --no-ff (no-fast-forward) to preserve history docs/gitflow.md:19-19, docs/gitflow.md:34-34.
• release/*: Used to prepare for a new production release. Branched from develop and merged into both main and develop docs/gitflow.md:20-20, docs/gitflow.md:35-35.
• hotfix/*: Used for critical production fixes. Branched from main and merged into both main and develop docs/gitflow.md:21-21, docs/gitflow.md:36-36.

For a detailed breakdown of naming conventions, merge policies, and multi-repo synchronization rules, see GitFlow Branching Strategy.

Release Lifecycle

The release process is a manual sequence of version bumping, branch merging, and tagging. Because the repository does not use automated version synchronization scripts for the package.json file, developers (and AI agents) must manually update version strings during the release or hotfix phase docs/gitflow.md:48-50.

Versioning Rules

• No 'v' Prefix: Tags and branch names must exclude the 'v' prefix (e.g., 0.13.2, not v0.13.2) docs/gitflow.md:65-66.
• Increment Logic: Hotfixes increment the patch version, while releases increment the minor version docs/gitflow.md:68-69.

Pre-commit Hook

The repository includes a pre-commit hook located at .githooks/pre-commit .githooks/pre-commit:1-10. This hook executes node scripts/version-sync.mjs to attempt synchronization of the package.json version on release and hotfix branches before a commit is finalized .githooks/pre-commit:5-5.

For a step-by-step guide on the release flow and hook behavior, see Release Lifecycle & Pre-commit Hooks.

Workflow Integration

The following diagram illustrates how the GitFlow branches interact with the repository's core files and the release execution logic.

Branch and Entity Relationship

Title: GitFlow Branching to Code Entity Mapping

Code
graph TD
    subgraph "Main Branches"
        MAIN["main (Production)"]
        DEV["develop (Integration)"]
    end

    subgraph "Temporary Branches"
        FEAT["feature/slug"]
        REL["release/x.y.z"]
        HOT["hotfix/x.y.z"]
    end

    subgraph "Code Entities & Config"
        PKG["package.json (version)"]
        SYNC_SCRIPT["scripts/version-sync.mjs"]
        HOOK[".githooks/pre-commit"]
    end

    DEV -->|"git checkout -b"| FEAT
    FEAT -->|"git merge --no-ff"| DEV
    
    DEV -->|"git checkout -b"| REL
    REL -->|"manual update"| PKG
    REL -.->|"triggers"| HOOK
    HOOK -->|"executes"| SYNC_SCRIPT
    
    REL -->|"git merge --no-ff"| MAIN
    MAIN -->|"git merge"| DEV
    
    MAIN -->|"git checkout -b"| HOT
    HOT -->|"manual update"| PKG

Sources: docs/gitflow.md:18-45, docs/gitflow.md:52-61, .githooks/pre-commit:1-10

Commit Guardrails

A critical rule for this repository is the Explicit Instruction policy. AI agents are strictly forbidden from committing changes automatically. They must wait for a specific user prompt (e.g., "commit" or "procedi con il commit") before executing any git commit command docs/gitflow.md:5-14.

When instructed to "commit and push everything," the procedure requires running git add -A across all repositories in the workspace (frontend, backend, and microservices) to ensure total synchronization docs/gitflow.md:93-98.

Repository Sync Workflow

Title: Multi-Repo Commit Logic

Code
sequenceDiagram
    participant User
    participant Agent
    participant Git as "git (microservices/)"
    
    User->>Agent: "Iniziamo un nuovo task: timezone support"
    Agent->>Git: git checkout -b feature/iana-timezone
    Note over Agent, Git: Development work occurs...
    User->>Agent: "Procedi con il commit"
    Agent->>Git: git add -A
    Agent->>Git: git commit -m "feat: implement iana timezone"
    Agent->>Git: git push origin feature/iana-timezone

Sources: docs/gitflow.md:102-108, docs/gitflow.md:93-98, docs/gitflow.md:11-14

---

Child Pages:

• GitFlow Branching Strategy
• Release Lifecycle & Pre-commit Hooks

---