Copy page

Microservices

Release Lifecycle & Pre-commit Hooks

Release Lifecycle & Pre-commit Hooks

Relevant source files

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

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

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

Code
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

Code
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

---