Homebridge SmartHQ PR Workflow

You are working on the **homebridge-smarthq** project, which uses a structured branch management and pull request workflow with beta releases and semantic versioning.

Branch Structure

Core Rules

1. **ALL pull requests MUST target a beta branch first, NEVER directly to `latest`**

2. **Issues MUST be labeled with `patch`, `minor`, or `major` before work begins**

3. **Beta branch version MUST match the semantic version implied by the issue label**

Semantic Version Labels

Before starting work on any issue, verify one of these labels is set:

| Label | Use Case | Examples |

|-------|----------|----------|

| `patch` | Bug fixes, security patches, documentation updates | Bug fixes, typos, dependency updates |

| `minor` | New features, enhancements, backwards-compatible additions | New device support, new configuration options |

| `major` | Breaking changes, API changes, backwards-incompatible modifications | Architecture changes, API redesigns |

Determining Target Branch

Step 1: Check Current State

```bash

Check current stable version

git checkout latest

git pull origin latest

cat package.json | grep version

Check for existing beta branches

git branch -r | grep beta

```

Step 2: Choose or Create Beta Branch

| Change Type | Current Stable | Target Branch | Action |

|-------------|---------------|---------------|--------|

| Patch to stable | 0.4.0 | `beta-0.4.1` | Create if doesn't exist |

| Patch to beta | 0.5.0-beta.x | `beta-0.5.0` | Use existing |

| Minor feature | 0.4.0 | `beta-0.5.0` | Use existing (currently active) |

| Major breaking | 0.4.0 | `beta-1.0.0` | Create from `latest` or current beta |

Step 3: Create Beta Branch (if needed)

```bash

Fetch latest changes

git fetch origin

Checkout base branch (usually 'latest' for new versions)

git checkout latest

git pull origin latest

Create and push new beta branch

git checkout -b beta-X.Y.Z

git push origin beta-X.Y.Z

```

PR Creation Workflow

Pre-Flight Checklist

Before creating any PR, verify:

Example Workflows

#### Bug Fix (Patch) Example

```bash

Issue labeled: patch

Target: beta-0.4.1 (for stable) or beta-0.5.0 (for beta)

If targeting stable release patches:

git fetch origin

git checkout latest

git pull origin latest

git checkout -b beta-0.4.1 # Only if doesn't exist

git push origin beta-0.4.1

Create feature branch

git checkout -b fix/issue-description

Make changes, commit

git push origin fix/issue-description

Create PR targeting beta-0.4.1

```

#### New Feature (Minor) Example

```bash

Issue labeled: minor

Target: beta-0.5.0 (currently active)

Use existing beta branch

git fetch origin

git checkout beta-0.5.0

git pull origin beta-0.5.0

Create feature branch

git checkout -b feature/new-feature

Make changes, commit

git push origin feature/new-feature

Create PR targeting beta-0.5.0

```

#### Breaking Change (Major) Example

```bash

Issue labeled: major

Target: beta-1.0.0 (create if doesn't exist)

Create new major version beta branch

git fetch origin

git checkout beta-0.5.0 # or latest

git pull origin beta-0.5.0

git checkout -b beta-1.0.0

git push origin beta-1.0.0

Create feature branch

git checkout -b breaking/major-change

Make changes, commit

git push origin breaking/major-change

Create PR targeting beta-1.0.0

```

Release Process

1. **Beta releases**: PRs merge to beta branches → trigger automated beta release workflow

2. **Stable releases**: Beta branches merge to `latest` → trigger main release workflow

Current Project Status

Common Commands Reference

```bash

View all remote branches

git branch -r

Check current package version

cat package.json | grep version

Create and switch to new beta branch from latest

git checkout latest && git pull && git checkout -b beta-X.Y.Z && git push origin beta-X.Y.Z

Create feature branch from beta

git checkout beta-X.Y.Z && git pull && git checkout -b feature/description

```

Error Prevention

**NEVER do this:**

**ALWAYS do this:**