Homebridge SmartHQ Branch Management

GitHub Copilot instructions for managing branches, pull requests, and releases in the homebridge-smarthq project using a beta-first workflow with semantic versioning.

Project Context

You are working on **homebridge-smarthq**, a Homebridge plugin project that follows a strict beta-first release workflow with semantic versioning.

Current Project State

Branch Targeting Rules

**CRITICAL**: All pull requests **MUST** target a beta branch first. Never create PRs directly to `latest`.

Workflow Instructions

Step 1: Verify Issue Labels

Before starting work on any issue, ensure it has one of these labels:

If the label is missing, request clarification before proceeding.

Step 2: Determine Target Beta Branch

Based on the issue label:

#### For `patch` fixes:

#### For `minor` features:

#### For `major` breaking changes:

Step 3: Create Beta Branch (If Needed)

If the appropriate beta branch doesn't exist:

1. **Determine next version** using semantic versioning:

- Check `package.json` in `latest` for current stable version

- Increment based on change type (patch/minor/major)

2. **Create beta branch**:

```bash

git fetch origin

git checkout latest

git pull origin latest

git checkout -b beta-X.Y.Z

git push origin beta-X.Y.Z

```

**Example**: For a minor update from 0.4.0 → create `beta-0.5.0`

Step 4: Create Feature Branch and PR

1. Create feature branch from target beta branch:

```bash

git fetch origin

git checkout beta-0.5.0 # or appropriate beta branch

git pull origin beta-0.5.0

git checkout -b feature/your-feature-name

```

2. Make focused, minimal changes for the specific issue

3. Create PR targeting the beta branch (NOT `latest`)

4. Ensure PR description references the issue number

Step 5: PR Review Checklist

Before submitting, verify:

Branch Naming Conventions

Release Process

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

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

Examples

Example 1: Bug Fix for Stable Release

```

Issue label: patch

Current stable: 0.4.0

Target branch: beta-0.4.1 (create from `latest` if doesn't exist)

Result: v0.4.1-beta.1 → ... → v0.4.1 (after testing)

```

Example 2: New Feature

```

Issue label: minor

Current stable: 0.4.0

Active beta: 0.5.0

Target branch: beta-0.5.0 (existing)

Result: v0.5.0-beta.5 → ... → v0.5.0 (after testing)

```

Example 3: Breaking Change

```

Issue label: major

Current beta: 0.5.0

Target branch: beta-1.0.0 (create from beta-0.5.0 or latest)

Result: v1.0.0-beta.1 → ... → v1.0.0 (after testing)

```

Key Principles

1. **Beta-first workflow**: All changes go through beta testing before reaching stable

2. **Semantic versioning**: Version numbers reflect the nature of changes

3. **Focused changes**: Each PR addresses one specific issue

4. **Label-driven**: Issue labels determine versioning strategy

5. **Never skip beta**: Direct merges to `latest` are prohibited

Error Prevention

**Common mistakes to avoid**:

Questions to Ask

When uncertain, verify:

1. "Does this issue have a semantic version label (patch/minor/major)?"

2. "Which beta branch should I target based on the label?"

3. "Does the target beta branch exist, or do I need to create it?"

4. "Am I branching from the correct beta branch, not `latest`?"

5. "Does my PR target the beta branch?"

By following these instructions, you ensure proper version management, thorough beta testing, and maintain stability of the main codebase.