Development & Contribution Workflow

develop-branchConventional CommitsAutomated CI/CD

This guide documents the development workflow, branching strategy, commit conventions, and release automation used across the PiVirt ecosystem.

1. Version Control & GitFlow Strategy

PiVirt uses a simplified GitFlow model with develop as the single integration branch.

feature/xxx  ──┐
fix/xxx      ──┤
sentinel/xxx ──┤──►  develop  ──►  tag v0.0.XX
renovate/xxx ──┤
chore/xxx    ──┘

Key Rules

develop — The only permanent branch. All feature work and bug fixes merge here.
No main/master branch — Releases are tagged directly from develop.
Feature branches are deleted immediately after merge.

2. Branch Naming Conventions

All branch names must be lowercase with hyphens only:

Prefix	Purpose	Base Branch	Merges To
`feature/<slug>`	New features, enhancements	`develop`	`develop`
`fix/<slug>`	Bug fixes	`develop`	`develop`
`bugfix/<slug>`	Bug fixes (alternative)	`develop`	`develop`
`sentinel/<slug>`	Automated security fixes	`develop`	`develop`
`renovate/<slug>`	Automated dependency updates	`develop`	`develop`
`chore/<slug>`	Maintenance, CI, tooling	`develop`	`develop`
`release/<version>`	Release candidates (minor/major)	`develop`	`develop`
`hotfix/<slug>`	Urgent production fixes	`tag`	`develop`

3. Commit Convention

PiVirt strictly follows the Conventional Commits specification:

type(scope): description

# Types: feat, fix, refactor, chore, docs, test, perf, security, revert, style
# Scopes: agent, pivirtd, pvcli, iscsiman, deployer, osinfodb, pkg, ci, meta, deps

Examples

feat(agent): implement pivirtd Clone via snapshot + disk copy
fix(pivirtd): correct IP parsing for IPv6 addresses in port detection
refactor(agent): migrate agent_service.go to hypervisor abstraction
chore(config): default hypervisor_type to pivirtd with pivirt storage paths
test(agent): add integration test suite for pivirtd stub client
security(pkg): fix path traversal in storage volume deletion
docs(meta): add structured PR template with machine-parseable metadata

4. Pull Request Workflow

Branch from develop:

git checkout -b feature/my-new-feature develop

Run Local Pre-flight Verification:

go test ./... -short
go vet ./...
golangci-lint run --config=.golangci.yml
go build ./...

Open Pull Request: Include the machine-parseable metadata header in the PR description:

<!--
pr-type:          feat|fix|refactor|chore|docs|test|perf|security|revert
area:             agent|pivirtd|pvcli|iscsiman|deployer|osinfodb|pkg|ci|docs|meta
breaking:         no|yes
security-impact:  no|yes
security-severity: none|critical|high|medium|low
release-notes-entry: One-line summary for changelog
-->

CI Gates & Automated Merge: All PRs merge into develop via squash merge — one commit per PR matching the PR title.

5. Automated CI/CD & Releases

Job	Trigger	What it does
Test	Every PR	Runs `go test ./... -short`
Lint & Coverage	Push to `develop`	`golangci-lint run`, `go test -coverprofile`
Build Binaries	Push to `develop`	Builds all 7 binaries: `agent`, `cloudhypervisor`, `deployer`, `iscsiman`, `osinfodb`, `pivirtd`, `pvcli`
Auto-Tag	Push to `develop`	Automatically increments patch version `v0.0.XX`
Trigger Dependents	Push to `develop`	Dispatches integration triggers to downstream services

Docker Registry

Container images are published to the internal registry:

registry.pilab.hu/pilab-cloud/cloud-manager
registry.pilab.hu/pilab-cloud/cloud-<app>