# Versioning & GitFlow

# Versioning & GitFlow

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

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

- [.githooks/pre-commit](.githooks/pre-commit)
- [.windsurfintructions](.windsurfintructions)
- [AGENTS.md](AGENTS.md)
- [README.md](README.md)
- [docs/ai/README.md](docs/ai/README.md)
- [docs/ai/SKILLS.md](docs/ai/SKILLS.md)
- [docs/ai/patterns.md](docs/ai/patterns.md)
- [docs/gitflow.md](docs/gitflow.md)
- [package.json](package.json)
- [scripts/version-sync.mjs](scripts/version-sync.mjs)
- [src/lib/api.ts](src/lib/api.ts)
- [src/routes/login/+page.svelte](src/routes/login/+page.svelte)
- [vite.config.ts](vite.config.ts)

</details>



This page documents the automated versioning pipeline and the Git branching strategy used in the Primebrick Frontend. The system ensures that the version declared in `package.json` remains synchronized with Git tags and branch names, enforcing a strict release and hotfix lifecycle.

## Automated Version Synchronization

The project utilizes a custom script, `version-sync.mjs`, to automate the update of the `package.json` version field based on the current Git context. This script acts as a safeguard to prevent version mismatches during the build and release processes.

### Implementation Details
The script is located at `scripts/version-sync.mjs` and is integrated into the development lifecycle via `package.json` scripts. It is executed automatically as a `prebuild` hook [package.json:9-9]().

**Key Functions:**
- `latestTagVersion()`: Scans the Git history for tags matching the `0.*.*` pattern, parses them, and returns the highest version found [scripts/version-sync.mjs:33-46]().
- `nextVersion(kind, latest)`: Calculates the next semantic version. A `release` increments the **minor** version and resets the patch to 0, while a `hotfix` increments the **patch** version [scripts/version-sync.mjs:48-52]().
- `parseTag(tag)`: Uses a regex `^(0)\.(\d+)\.(\d+)$` to ensure tags follow the strictly required format without a `v` prefix [scripts/version-sync.mjs:16-21]().

### Data Flow: Version Validation
The script follows a specific logic flow to determine if `package.json` should be updated or if the build should fail:

1. **Branch Detection**: It identifies the current branch name using `git rev-parse`.
2. **Kind Identification**: It checks if the branch starts with `release/` or `hotfix/`. If it is a feature or development branch, the script exits silently [scripts/version-sync.mjs:69-75]().
3. **Validation**: It calculates the "Expected Version" based on the latest tag. If the current branch name does not match `kind/expected-version`, the process exits with an error, blocking the build [scripts/version-sync.mjs:81-91]().
4. **Update**: If the branch name is valid but `package.json` still reflects an old version, the script overwrites the `version` field in `package.json` [scripts/version-sync.mjs:97-104]().

### Version Sync Logic Diagram

```mermaid
graph TD
    Start["npm run build"] --> Prebuild["node scripts/version-sync.mjs"]
    Prebuild --> GetBranch["getBranchName()"]
    GetBranch --> IsSpecial{Branch starts with release/ or hotfix/?}
    IsSpecial -- No --> Exit[Exit Success]
    IsSpecial -- Yes --> GetLatest["latestTagVersion()"]
    GetLatest --> CalcExpected["nextVersion(kind, latest)"]
    CalcExpected --> ValidateBranch{Branch Name == Expected?}
    ValidateBranch -- No --> Fail[Exit 1: Branch Name Mismatch]
    ValidateBranch -- Yes --> CheckPkg{package.json version == Expected?}
    CheckPkg -- Yes --> Exit
    CheckPkg -- No --> UpdatePkg["writeJson('package.json', expected)"]
    UpdatePkg --> Exit
```
Sources: [scripts/version-sync.mjs:1-109](), [package.json:8-10]()

---

## GitFlow Conventions

The repository follows a strict GitFlow workflow to manage features, releases, and production fixes.

### Branch Types
| Branch Prefix | Base Branch | Merge Target | Purpose |
|:---|:---|:---|:---|
| `feature/` | `develop` | `develop` | New functionality or UI changes. |
| `release/` | `develop` | `main` & `develop` | Preparing for a new production deployment (Minor bump). |
| `hotfix/` | `main` | `main` & `develop` | Urgent fixes for production (Patch bump). |

### Branch Management Rules
- **No Direct Commits**: Working directly on `develop` or `main` is strictly prohibited [docs/gitflow.md:18-18]().
- **Merge Strategy**: All merges into `main` or `develop` from a feature/release/hotfix branch must use the `--no-ff` (no-fast-forward) flag to preserve the branch history [docs/gitflow.md:34-36]().
- **Cleanup**: After a successful merge and push to origin, branches must be deleted both locally and on the remote (`origin`) [docs/gitflow.md:40-42]().

### Tag Naming Rules
The project enforces a specific format for Git tags to ensure compatibility with the automated scripts:
- **No 'v' Prefix**: Tags must be `0.32.0`, not `v0.32.0` [docs/gitflow.md:70-71]().
- **Derivation**: The tag must exactly match the version number in the `release/` or `hotfix/` branch name [docs/gitflow.md:72-72]().

Sources: [docs/gitflow.md:16-75](), [AGENTS.md:48-53]()

---

## Commit & Hook Policy

### Pre-commit Hook
The repository includes a `.githooks/pre-commit` hook (managed via the workspace setup). This hook ensures that code quality is maintained before any commit is finalized. It typically triggers the `pnpm run check` command, which executes `svelte-check` and `tsc` [package.json:13-13]().

### AI Agent Constraints
AI agents (like Devin or Windsurf) are subject to critical restrictions regarding Git operations:
- **Explicit Instruction**: Agents MUST NEVER commit automatically. They must wait for a user to explicitly say "commit" or "procedi con il commit" [AGENTS.md:3-9]().
- **New Tasks**: When starting a new task, agents must infer a slug and create a `feature/<slug>` branch before making any changes [docs/gitflow.md:107-114]().

### GitFlow Entity Mapping Diagram

This diagram maps the natural language GitFlow concepts to the specific code entities and scripts that enforce them.

```mermaid
classDiagram
    class GitRepository {
        +main_branch
        +develop_branch
        +tags: 0.*.*
    }
    class VersionSyncScript {
        <<script>>
        +scripts/version-sync.mjs
        +latestTagVersion()
        +nextVersion()
    }
    class PackageJson {
        +version: string
        +prebuild: script
    }
    class GitHooks {
        +.githooks/pre-commit
    }

    VersionSyncScript ..> GitRepository : "reads tags via git tag --list"
    VersionSyncScript ..> PackageJson : "updates version field"
    PackageJson ..> VersionSyncScript : "triggers via prebuild hook"
    GitHooks ..> PackageJson : "runs pnpm run check"
```
Sources: [scripts/version-sync.mjs:1-109](), [package.json:1-14](), [docs/gitflow.md:46-66]()

---

## Release & Hotfix Workflow

### Standard Release Procedure
1. Create a branch: `git checkout -b release/0.X.0` from `develop`.
2. Run `pnpm run build`. The `version-sync.mjs` script will detect the branch and update `package.json` to `0.X.0` [docs/gitflow.md:57-58]().
3. Merge to `main` using `--no-ff`.
4. Tag the commit on `main` with `0.X.0`.
5. Merge `main` back into `develop` to ensure the version update and any final release tweaks are propagated [docs/gitflow.md:62-62]().

### Hotfix Procedure
1. Create a branch: `git checkout -b hotfix/0.X.Y` from `main`.
2. The `version-sync.mjs` script ensures the patch version `Y` is correctly incremented based on the last tag [scripts/version-sync.mjs:50-50]().
3. Follow the same merge and tagging steps as the release procedure.

Sources: [docs/gitflow.md:56-66](), [scripts/version-sync.mjs:48-52]()

---