# GitFlow Branching Strategy

# GitFlow Branching Strategy

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

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

- [docs/gitflow.md](docs/gitflow.md)

</details>



This page defines the mandatory GitFlow branching model and versioning standards for the Primebrick v3 Microservices repository. Adherence to these rules ensures architectural consistency across microservices and prevents integration conflicts in the multi-repository workspace.

## 1. Core Branching Model

The repository operates on two permanent branches and three types of temporary branches. Direct commits to permanent branches are strictly prohibited [docs/gitflow.md:18-18]().

### 1.1 Permanent Branches
*   **`main`**: Reflects production-ready code. All code in `main` must be tagged with a version number [docs/gitflow.md:35-36]().
*   **`develop`**: The integration branch for features. It serves as the source for all `feature/*` and `release/*` branches [docs/gitflow.md:19-20]().

### 1.2 Temporary Branches
| Branch Type | Naming Convention | Source Branch | Target Branch |
| :--- | :--- | :--- | :--- |
| **Feature** | `feature/<slug>` | `develop` | `develop` |
| **Release** | `release/<version>` | `develop` | `main` & `develop` |
| **Hotfix** | `hotfix/<version>` | `main` | `main` & `develop` |

**Sources:** [docs/gitflow.md:16-22](), [docs/gitflow.md:31-36]()

## 2. Feature Workflow

Feature branches are used for developing new functionality or internal improvements. 

1.  **Creation**: A slug must be inferred from the task context (lowercase, kebab-case, ASCII only) [docs/gitflow.md:104-104](). The branch is created from an updated `develop` branch [docs/gitflow.md:19-19]().
2.  **Implementation**: All changes are committed to the feature branch. AI agents must verify the current branch using `git branch --show-current` before modifying files [docs/gitflow.md:107-107]().
3.  **Closing**: Features are merged back into `develop` using the `--no-ff` (no-fast-forward) flag to preserve the branch history [docs/gitflow.md:34-34]().

### GitFlow Entity Transition
The following diagram illustrates the transition of code states through the GitFlow lifecycle, mapping logical phases to specific Git commands and branch entities.

```mermaid
graph TD
    subgraph "Natural Language / Intent"
        StartTask["'Start a new task'"]
        CompleteTask["'Task finished'"]
    end

    subgraph "Code Entity Space"
        DevelopBranch["develop branch"]
        FeatureBranch["feature/slug branch"]
        GitMerge["git merge --no-ff"]
        GitPush["git push origin develop"]
    end

    StartTask -->|"git checkout -b feature/slug"| FeatureBranch
    FeatureBranch -->|"Development Commits"| FeatureBranch
    FeatureBranch -->|"git checkout develop"| DevelopBranch
    DevelopBranch --> GitMerge
    GitMerge -->|"Merge feature/slug"| DevelopBranch
    DevelopBranch --> GitPush
    CompleteTask -->|"git branch -d feature/slug"| DevelopBranch
```
**Sources:** [docs/gitflow.md:31-42](), [docs/gitflow.md:100-108]()

## 3. Release and Hotfix Procedures

Version management in this repository is manual. There are no automated scripts for synchronizing versions across `package.json` files [docs/gitflow.md:48-50]().

### 3.1 Versioning Rules
*   **Release**: Increments the **MINOR** version (e.g., `0.13.2` → `0.14.0`) [docs/gitflow.md:69-69]().
*   **Hotfix**: Increments the **PATCH** version (e.g., `0.13.1` → `0.13.2`) [docs/gitflow.md:68-68]().
*   **Tagging**: Tags must **NOT** use a 'v' prefix. Example: `0.13.2`, not `v0.13.2` [docs/gitflow.md:65-66]().

### 3.2 Release Execution Flow
The sequence for a release is rigid to ensure `main` and `develop` stay synchronized:
1.  Create `release/<version>` from `develop` [docs/gitflow.md:53-53]().
2.  Manually update version in `package.json` and commit [docs/gitflow.md:54-55]().
3.  Merge to `main` with `--no-ff` [docs/gitflow.md:35-35]().
4.  Tag the `main` branch with the version number (no 'v' prefix) [docs/gitflow.md:57-57]().
5.  Merge `main` back into `develop` to propagate the version bump and any release-specific fixes [docs/gitflow.md:59-59]().
6.  Delete the temporary branch locally and on `origin` [docs/gitflow.md:40-42]().

**Sources:** [docs/gitflow.md:46-70]()

## 4. Multi-Repository Synchronization

When working within a meta-workspace that includes multiple repositories (e.g., frontend, backend, and microservices), synchronization must be atomic across all units.

### 4.1 Global Add Policy
When instructed to "commit and push everything," the following sequence is mandatory:
1.  Navigate to each repository root or the workspace root.
2.  Execute `git add -A` to stage all changes, including untracked files [docs/gitflow.md:94-94]().
3.  Do **not** filter files by task relevance; every change in the workspace must be captured [docs/gitflow.md:97-97]().
4.  Commit and push all branches to their respective origins [docs/gitflow.md:95-96]().

### 4.2 Workspace Navigation
For microservices-specific tasks initiated from a meta-workspace root, commands should be prefixed with directory navigation:
`cd microservices && git <command>` [docs/gitflow.md:82-82]().

**Sources:** [docs/gitflow.md:91-99](), [docs/gitflow.md:80-82]()

## 5. Commit Guardrails

To prevent accidental data loss or unauthorized history modification, the following guardrails are enforced:

*   **Explicit Instruction**: AI agents must never run `git commit` without an explicit user command (e.g., "commit" or "procedi con il commit") [docs/gitflow.md:7-11]().
*   **No Message Approval**: Agents should write appropriate commit messages directly without opening editors or asking for approval once the instruction to commit is received [docs/gitflow.md:87-89]().
*   **No-Fast-Forward**: The `--no-ff` flag is mandatory for all merges to permanent branches to ensure the existence of a merge commit [docs/gitflow.md:33-36]().

### Branch Management Logic
The following diagram maps the branch closing procedure to the specific Git CLI operations required to maintain repository health.

```mermaid
graph LR
    subgraph "Cleanup Phase"
        LocalDel["git branch -d"]
        RemoteDel["git push origin --delete"]
    end

    subgraph "Integration Phase"
        MergeMain["git merge --no-ff into main"]
        TagMain["git tag <version>"]
        BackMerge["git merge main into develop"]
    end

    ReleaseBranch["release/* or hotfix/*"] --> MergeMain
    MergeMain --> TagMain
    TagMain --> BackMerge
    BackMerge --> LocalDel
    LocalDel --> RemoteDel
```
**Sources:** [docs/gitflow.md:31-45](), [docs/gitflow.md:52-61]()

---