# GitFlow, Versioning, and CI Hooks

# GitFlow, Versioning, and CI Hooks

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

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

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

</details>



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**
```mermaid
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**
```mermaid
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**
```mermaid
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]()

---