# Version Control & Release Process

# Version Control & Release Process

<details>
<summary>Relevant source files</summary>

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

- [.githooks/pre-commit](.githooks/pre-commit)
- [docs/gitflow.md](docs/gitflow.md)

</details>



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](#5.1)**.

## 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](#5.2)**.

## 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
```mermaid
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
```mermaid
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](#5.1)**
*   **[Release Lifecycle & Pre-commit Hooks](#5.2)**

---