Copy page

Microservices

GitFlow Branching Strategy

GitFlow Branching Strategy

Relevant source files

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

• docs/gitflow.md

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.

Code
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.

Code
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

---