Copy page

Backend

GitFlow, Versioning, and CI Hooks

GitFlow, Versioning, and CI Hooks

Relevant source files

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

• .devin/rules/always-check-rules-first.md
• .devin/rules/code-guardrails.md
• .devin/rules/file-operations.md
• .devin/rules/temp-files.md
• .devin/rules/workflow.md
• .githooks/post-merge
• .githooks/pre-commit
• AGENTS.md
• README.md
• docs/gitflow.md
• scripts/database-patch-apply.ts
• scripts/database-patch-compare.ts
• scripts/version-sync.mjs

This page documents the development lifecycle, branching strategies, version synchronization mechanisms, and automated Git hooks used in the Primebrick backend. It ensures consistency across environments and provides clear operational constraints for both human developers and AI agents.

GitFlow Branching Strategy

The repository follows a strict GitFlow model to manage features, releases, and hotfixes. Direct commits to develop or main are strictly prohibited docs/gitflow.md:18-18.

Branch Types and Lifecycle

Branch Type	Base Branch	Target Branch	Purpose
Feature	develop	develop	New functionality or refactors. Named feature/<slug>.
Release	develop	main & develop	Preparation for a new production release. Named release/<version>.
Hotfix	main	main & develop	Urgent production fixes. Named hotfix/<version>.

Branch Closing Procedure

When closing a branch, a non-fast-forward merge (--no-ff) is required to preserve history docs/gitflow.md:34-36.

1. Merge to the appropriate base branch.
2. Push the base branch to origin.
3. Delete the branch locally and on origin.
4. For Release/Hotfix: Merge main back into develop to ensure synchronization docs/gitflow.md:44-44.

Diagram: Branching Data Flow

Code
graph TD
    subgraph "Production"
        MAIN["main"]
    end
    subgraph "Development"
        DEV["develop"]
    end
    subgraph "Workflows"
        FEAT["feature/slug"]
        REL["release/0.x.0"]
        HOT["hotfix/0.x.x"]
    end

    DEV -->|"git checkout -b"| FEAT
    FEAT -->|"git merge --no-ff"| DEV
    DEV -->|"git checkout -b"| REL
    REL -->|"git merge --no-ff"| MAIN
    MAIN -->|"git merge"| DEV
    MAIN -->|"git checkout -b"| HOT
    HOT -->|"git merge --no-ff"| MAIN
    MAIN -->|"git tag"| TAGS["Git Tags"]

Sources: docs/gitflow.md:16-45

---

Automated Version Synchronization

The package.json version is not updated manually. Instead, it is managed by the version-sync.mjs script, which runs as a prebuild hook docs/gitflow.md:48-50.

version-sync.mjs Logic

The script performs the following operations:

1. Branch Detection: Identifies if the current branch is a release/ or hotfix/ branch scripts/version-sync.mjs:69-73.
2. Tag Calculation: Fetches the latest Git tag using git tag --list "0.*.*" scripts/version-sync.mjs:36-36.
3. Version Increment:
   • Release: Increments the minor version and resets patch to 0 (e.g., 0.13.2 -> 0.14.0) scripts/version-sync.mjs:49-49.
   • Hotfix: Increments the patch version (e.g., 0.13.2 -> 0.13.3) scripts/version-sync.mjs:50-50.
4. Validation: Enforces that the branch name matches the calculated next version. If the latest tag is 0.22.0 and the branch is release/0.24.0, the script fails scripts/version-sync.mjs:81-91.
5. Update: Automatically updates the version field in package.json scripts/version-sync.mjs:102-103.

Diagram: Version Sync Logic

Code
graph LR
    START["git branch"] --> BRANCH_KIND{"Branch Type?"}
    BRANCH_KIND -- "release/*" --> CALC_MINOR["Increment Minor"]
    BRANCH_KIND -- "hotfix/*" --> CALC_PATCH["Increment Patch"]
    BRANCH_KIND -- "other" --> EXIT["Exit 0"]
    
    CALC_MINOR --> LATEST_TAG["latestTagVersion()"]
    CALC_PATCH --> LATEST_TAG
    
    LATEST_TAG --> VALIDATE{"Branch Name == Expected?"}
    VALIDATE -- "No" --> FAIL["Exit 1 (Error)"]
    VALIDATE -- "Yes" --> UPDATE_PKG["Update package.json"]

Sources: scripts/version-sync.mjs:48-107, docs/gitflow.md:68-75

---

Git Hooks and CI Automation

The project uses Git hooks located in .githooks/ to automate database consistency. Users must configure their local environment to use these hooks: git config core.hooksPath .githooks AGENTS.md:59-61.

Post-Merge Hook (.githooks/post-merge)

Triggered after a git pull or git merge. Its primary responsibility is to keep the local database schema in sync with the codebase AGENTS.md:63-63.

• Action: Executes pnpm run db:migrate githooks/post-merge:25-25.
• Skip Logic: Skips execution if PB_SKIP_POST_MERGE_DB_MIGRATE=1 is set or if no database connection is available githooks/post-merge:7-21.
• Safety: It specifically does not run db:meta:compare, as that is reserved for model development workflows AGENTS.md:52-52.

Database Patching Workflow

The system distinguishes between generating patches and applying them:

1. Generation (db:meta:compare): Uses database-patch-compare.ts to compare the ENTITY_REGISTRY against the live database schema and generate .sql files in db-meta/patches/ scripts/database-patch-compare.ts:26-77.
2. Application (db:migrate): Uses database-patch-apply.ts to execute pending SQL files. It tracks applied patches in the public.primebrick_database_patch table using a content_sha256 to ensure idempotency scripts/database-patch-apply.ts:7-12.

Diagram: Entity to Database Synchronization

Code
sequenceDiagram
    participant Dev as "Developer (@Entity)"
    participant Reg as "ENTITY_REGISTRY"
    participant Comp as "database-patch-compare.ts"
    participant Disk as "db-meta/patches/*.sql"
    participant App as "database-patch-apply.ts"
    participant DB as "PostgreSQL (primebrick_database_patch)"

    Dev->>Reg: Modify Class with @Entity
    Note over Dev, Reg: pnpm run db:meta:compare
    Reg->>Comp: buildEntitySnapshot()
    Comp->>Disk: Write Timestamped .sql Patch
    Note over Disk, DB: pnpm run db:migrate (or post-merge)
    Disk->>App: Read sorted .sql files
    App->>DB: Check SHA256 in registry table
    DB-->>App: Patch missing?
    App->>DB: BEGIN; Execute SQL; INSERT registry; COMMIT;

Sources: scripts/database-patch-compare.ts:15-131, scripts/database-patch-apply.ts:18-145, AGENTS.md:50-53

---

AI Agent Operational Constraints

AI agents (such as Devin) are subject to strict guardrails to prevent unauthorized changes and repository pollution.

Critical Safety Rules

• No Automatic Commits: AI agents MUST NEVER run git commit without explicit user instruction (e.g., "procedi con il commit") AGENTS.md:5-9.
• Branching: Agents must infer a slug and create a feature/<slug> branch before making any changes docs/gitflow.md:107-112.
• Temporary Files: All temporary scripts or patches must be created in a system /tmp/ or temp/ directory outside the project repositories and cleaned up immediately devin/rules/temp-files.md:11-24.
• Error Handling: If a command fails twice, the agent must STOP and escalate to the user devin/rules/code-guardrails.md:7-10.

Workflow Enforcement

• Tic-Toc Planning: Agents must analyze requirements and create a plan in the ai-plans/ folder before writing code. Execution is halted until the user says "PROCEED" devin/rules/workflow.md:11-16.
• File Verification: Agents must use empirical tools (Test-Path, ls, grep) to verify file states rather than relying on IDE memory devin/rules/file-operations.md:15-20.

Sources: AGENTS.md:1-10, docs/gitflow.md:5-15, devin/rules/code-guardrails.md:4-15, devin/rules/temp-files.md:5-36

---