Copy page

Frontend

Versioning & GitFlow

Versioning & GitFlow

Relevant source files

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

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

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

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

Code
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

---