# Release Lifecycle & Pre-commit Hooks

# Release Lifecycle & Pre-commit Hooks

<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 details the release process for the Primebrick v3 Microservices repository, encompassing the GitFlow-based release lifecycle and the automated behaviors of the pre-commit hooks. The repository follows a strict manual versioning policy complemented by a synchronization hook to ensure consistency across the monorepo.

## Release Lifecycle Process

The release process follows a structured GitFlow progression. Unlike feature development, releases and hotfixes require manual version management in the root `package.json` and specific merging patterns to maintain synchronization between the `main` (production) and `develop` (integration) branches.

### Step-by-Step Release Flow

The standard lifecycle for a release (minor version increment) or hotfix (patch version increment) follows these steps:

1.  **Branch Creation**: A new branch is created from the appropriate base.
    *   **Release**: `git checkout -b release/<version>` from updated `develop` [docs/gitflow.md:20-20]().
    *   **Hotfix**: `git checkout -b hotfix/<version>` from `main` [docs/gitflow.md:21-21]().
2.  **Manual Version Bump**: The version field in the root `package.json` must be manually updated to match the target version [docs/gitflow.md:50-54]().
3.  **Commit & Verification**: The version change is committed. During this stage, the pre-commit hook triggers the version synchronization script [docs/gitflow.md:55-55]().
4.  **Merging to Main**: The release/hotfix branch is merged into `main` using the `--no-ff` (no-fast-forward) flag to preserve history [docs/gitflow.md:35-36]().
5.  **Tagging**: A tag is created on `main`. Tags **must not** include a 'v' prefix (e.g., `0.14.0`, not `v0.14.0`) [docs/gitflow.md:65-69]().
6.  **Back-porting**: `main` is merged back into `develop` to ensure that the new version and any hotfix changes are integrated into the development stream [docs/gitflow.md:59-59]().
7.  **Cleanup**: The temporary release/hotfix branch is deleted both locally and on the origin remote [docs/gitflow.md:40-42]().

### Versioning Rules

| Type | Source Branch | Version Increment | Tag Example |
| :--- | :--- | :--- | :--- |
| **Release** | `develop` | Minor (e.g., 0.13.2 -> 0.14.0) | `0.14.0` |
| **Hotfix** | `main` | Patch (e.g., 0.13.1 -> 0.13.2) | `0.13.2` |

**Sources:** [docs/gitflow.md:52-69](), [docs/gitflow.md:19-21]()

## Pre-commit Hook Behavior

The repository utilizes a Git hook located at `.githooks/pre-commit` to maintain version integrity during the commit process. This hook is particularly critical during the release lifecycle to ensure that the manual version bump in the root `package.json` is correctly propagated.

### Implementation Logic

When a `git commit` command is executed, the following sequence occurs:

1.  **Script Execution**: The hook executes `node scripts/version-sync.mjs` [ .githooks/pre-commit:5-5]().
2.  **Version Synchronization**: The `version-sync.mjs` script (referenced in the hook) is responsible for ensuring that the version defined in the root `package.json` is consistent across any relevant sub-packages or internal manifests.
3.  **Automatic Staging**: If the synchronization script modifies the `package.json` file, the hook automatically runs `git add package.json` to include these changes in the current commit [ .githooks/pre-commit:8-8]().

### Data Flow: Release Commit

Release Branch Lifecycle to Code Entity Space
```mermaid
graph TD
    subgraph "Git Commands"
        A["git checkout -b release/0.14.0"] --> B["Manual Edit package.json"]
        B --> C["git commit -m 'Release 0.14.0'"]
    end

    subgraph "Pre-commit Hook Logic"
        C --> D["sh .githooks/pre-commit"]
        D --> E["node scripts/version-sync.mjs"]
        E --> F{"Changes detected?"}
        F -- "Yes" --> G["git add package.json"]
        F -- "No" --> H["Proceed with Commit"]
        G --> H
    end

    subgraph "Branch Finalization"
        H --> I["git merge --no-ff release/0.14.0 into main"]
        I --> J["git tag 0.14.0"]
    end
```

**Sources:** [ .githooks/pre-commit:1-10](), [docs/gitflow.md:52-60]()

## Branch Management & Cleanup

The "Branch Closing Procedure" is mandatory for all contributors and AI agents to prevent stale branches and repository bloat.

### Mandatory Closing Steps
1.  **Merge to Base**: Use `--no-ff` to ensure a merge commit is created, documenting the branch integration [docs/gitflow.md:33-36]().
2.  **Push Base**: Immediately push the updated `main` or `develop` branch [docs/gitflow.md:38-38]().
3.  **Local Deletion**: Delete the branch locally using `git branch -d` [docs/gitflow.md:40-40]().
4.  **Remote Deletion**: Delete the branch on the origin using `git push origin --delete` [docs/gitflow.md:42-42]().

### Entity Association: GitFlow Rules to Branch States

Release Branch Lifecycle to Code Entity Space
```mermaid
graph LR
    subgraph "Source Branches"
        DEV["develop branch"]
        MAIN["main branch"]
    end

    subgraph "Transient Branches"
        FEAT["feature/*"]
        REL["release/*"]
        HOT["hotfix/*"]
    end

    DEV -- "checkout -b" --> FEAT
    DEV -- "checkout -b" --> REL
    MAIN -- "checkout -b" --> HOT

    FEAT -- "merge --no-ff" --> DEV
    REL -- "merge --no-ff" --> MAIN
    HOT -- "merge --no-ff" --> MAIN
    
    MAIN -- "back-port merge" --> DEV
```

**Sources:** [docs/gitflow.md:18-21](), [docs/gitflow.md:31-45]()

## AI Agent Guardrails

AI agents (e.g., Devin) operating within this repository are subject to strict commit constraints to prevent unauthorized changes to the release history.

*   **Explicit Instruction**: Agents **MUST NEVER** commit changes without an explicit user command such as "commit" or "procedi con il commit" [docs/gitflow.md:5-14]().
*   **Multi-Repo Sync**: When instructed to "push everything," agents must perform `git add -A` across all repositories in the workspace (frontend, backend, and microservices) to maintain global state synchronization [docs/gitflow.md:93-99]().
*   **Branch Verification**: After creating a branch, agents must verify the current branch using `git branch --show-current` to ensure the working tree is correctly aligned [docs/gitflow.md:107-108]().

**Sources:** [docs/gitflow.md:7-14](), [docs/gitflow.md:94-98](), [docs/gitflow.md:107-108]()

---