# GitFlow and Branching Rules

# GitFlow and Branching Rules

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

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

- [.devin/rules/workflow.md](.devin/rules/workflow.md)
- [docs/gitflow.md](docs/gitflow.md)

</details>



This page outlines the mandatory GitFlow procedures for the `@primebrick/dal-pg` repository. These rules apply to both human contributors and AI agents to ensure codebase stability, consistent versioning, and clean repository history.

## Purpose and Scope

The branching strategy is designed to isolate development work, manage releases, and facilitate rapid hotfixing while maintaining a pristine `main` branch. It strictly enforces the "No `v` prefix" convention and requires explicit version synchronization within `package.json` prior to merging.

## Branch Naming Conventions

All work must be performed in dedicated branches. Direct commits to `develop` or `main` are strictly prohibited [docs/gitflow.md:18-18]().

| Branch Type | Source Branch | Naming Pattern | Purpose |
| :--- | :--- | :--- | :--- |
| **Feature** | `develop` | `feature/<slug>` | New functionality or refactoring. Slugs must be lowercase kebab-case [docs/gitflow.md:19-19, 105-105](). |
| **Release** | `develop` | `release/<version>` | Preparing a new production release. Increments MINOR version [docs/gitflow.md:20-20, 82-82](). |
| **Hotfix** | `main` | `hotfix/<version>` | Urgent production bug fixes. Increments PATCH version [docs/gitflow.md:21-21, 81-81](). |

### Versioning Rules
*   **No 'v' Prefix**: Do not use `v` in branch names (e.g., use `release/0.13.2`, not `release/v0.13.2`) [docs/gitflow.md:78-78]().
*   **Tagging**: Git tags must match the version exactly without a prefix (e.g., `0.13.2`) [docs/gitflow.md:79-80]().

## Branch Lifecycle and Data Flow

The following diagram illustrates the flow of code between branches and the synchronization requirements.

### GitFlow State Transition
```mermaid
graph TD
    Main["branch: main"]
    Develop["branch: develop"]
    Feature["branch: feature/&lt;slug&gt;"]
    Release["branch: release/&lt;version&gt;"]
    Hotfix["branch: hotfix/&lt;version&gt;"]

    Develop -- "checkout -b" --> Feature
    Feature -- "merge --no-ff" --> Develop
    
    Develop -- "checkout -b" --> Release
    Release -- "version bump commit" --> Release
    Release -- "merge --no-ff" --> Main
    Main -- "merge back" --> Develop

    Main -- "checkout -b" --> Hotfix
    Hotfix -- "version bump commit" --> Hotfix
    Hotfix -- "merge --no-ff" --> Main
    Main -- "merge back" --> Develop
```
**Sources:** [docs/gitflow.md:16-21](), [docs/gitflow.md:31-45]()

## Mandatory Closing Procedure

When a task is complete, branches must be closed using a non-fast-forward merge to preserve the group of commits as a single logical unit.

1.  **Merge to Base**: Use `git merge --no-ff <branch-name>` into the appropriate base branch (`develop` for features, `main` for release/hotfix) [docs/gitflow.md:33-36]().
2.  **Push Base**: Execute `git push origin <base-branch>` [docs/gitflow.md:38-38]().
3.  **Local Cleanup**: Delete the branch locally using `git branch -d <branch-name>` [docs/gitflow.md:40-40]().
4.  **Remote Cleanup**: Delete the branch on the origin using `git push origin --delete <branch-name>` [docs/gitflow.md:42-42]().
5.  **Alignment**: For Release and Hotfix branches, `main` must be merged back into `develop` to ensure `develop` contains the latest version bumps and fixes [docs/gitflow.md:44-44]().

## Version Synchronization

The `package.json` version is the source of truth for CI/CD. The version **must** be updated and committed on the `release/` or `hotfix/` branch before merging to `main` [docs/gitflow.md:48-50]().

### The `version-sync.mjs` Utility
The repository includes a script `scripts/version-sync.mjs` that manages this process [docs/gitflow.md:66-72]().
*   It detects the branch type and calculates the expected version from git tags.
*   It is triggered automatically via the `prebuild` hook during `pnpm run build` [docs/gitflow.md:68-68]().
*   **Manual Trigger**: Use `pnpm run version:auto` to sync the `package.json` before committing [docs/gitflow.md:54-54]().

### Correct Release Sequence
| Step | Command / Action | Purpose |
| :--- | :--- | :--- |
| 1 | `git checkout -b release/0.2.0` | Create release branch from `develop` |
| 2 | `pnpm run version:auto` | Run `version-sync.mjs` to update `package.json` |
| 3 | `git add package.json && git commit -m "bump version to 0.2.0"` | **CRITICAL**: Commit version before merge |
| 4 | `git checkout main && git merge --no-ff release/0.2.0` | Merge to production |
| 5 | `git tag 0.2.0` | Create immutable version tag |
| 6 | `git push origin main --tags` | Trigger CI for deployment |

**Sources:** [docs/gitflow.md:52-62]()

## Rules for AI Agents

AI agents (e.g., Devin) are subject to additional constraints to prevent unauthorized or accidental modifications.

1.  **Tic-Toc Planning**: Agents must generate a plan in `ai-plans/` and wait for a **"PROCEED"** instruction before any code modification [ .devin/rules/workflow.md:4-15]().
2.  **Explicit Commit Permission**: Agents **MUST NEVER** commit changes without explicit user instruction (e.g., "procedi con il commit") [docs/gitflow.md:7-14]().
3.  **Branching**: Agents must infer a branch slug and ensure they are on a `feature/` branch before the first tracked-file change [docs/gitflow.md:101-108]().

## Common Mistakes to Avoid

*   ❌ Committing directly on `develop` or `main` [docs/gitflow.md:86-86]().
*   ❌ Forgetting to delete branches (both local and origin) after merge [docs/gitflow.md:88-88]().
*   ❌ Using 'v' prefix in tags or branch names [docs/gitflow.md:89-89]().
*   ❌ Merging to `main` without committing the `package.json` version bump first [docs/gitflow.md:92-92]().
*   ❌ Creating commits before the feature branch has been created [docs/gitflow.md:87-87]().

**Sources:** [docs/gitflow.md:84-92]()

---