# Forgejo Workflow — Squadron TD Clone

## Branch Strategy

```
main          ← stable, always playable
develop       ← integration branch; PRs merge here first
feature/*     ← new features (e.g. feature/ghost-race-towers)
fix/*         ← bug fixes (e.g. fix/fighter-targeting)
data/*        ← balance/data-only changes (e.g. data/wave-12-rebalance)
chore/*       ← tooling, CI, docs (e.g. chore/update-gitignore)
```

**Rules:**
- `main` only receives merges from `develop` via a release PR.
- `develop` requires at least 1 review before merge.
- Feature branches are deleted after merge.
- Direct pushes to `main` and `develop` are protected.

---

## Labels

| Label | Color | Purpose |
|---|---|---|
| `type: feature` | #0075ca | New gameplay feature |
| `type: fix` | #d73a4a | Bug fix |
| `type: data` | #e4e669 | Balance/data change only |
| `type: chore` | #cccccc | Tooling, CI, refactor |
| `type: docs` | #0052cc | Documentation |
| `scope: towers` | #b60205 | Tower/fighter systems |
| `scope: economy` | #fbca04 | Mineral/gas/income systems |
| `scope: waves` | #006b75 | Wave definitions or spawning |
| `scope: ui` | #e99695 | HUD, menus, build panel |
| `scope: ai` | #c5def5 | Fighter or creep AI |
| `scope: multiplayer` | #bfd4f2 | Networking |
| `priority: high` | #b60205 | Blocking or critical |
| `priority: low` | #eeeeee | Nice to have |
| `status: blocked` | #e4e669 | Waiting on something else |
| `good first issue` | #7057ff | Approachable for new contributors |

---

## Milestones

| Milestone | Goal |
|---|---|
| v0.1 — Prototype | Single lane, 1 race, 10 waves, no economy |
| v0.2 — Economy | Workers, minerals, gas, send system |
| v0.3 — Full Waves | All 31 waves with data-driven definitions |
| v0.4 — All Races | 4 builder races with full tower trees |
| v0.5 — Multiplayer | 2-player co-op over local network |
| v1.0 — Release | Polished, tested, exportable build |

---

## Issue Templates

Create these as files in `.forgejo/ISSUE_TEMPLATE/` in your repo.

### `feature.md`
```markdown
---
name: Feature Request
about: Propose a new gameplay feature
labels: "type: feature"
---

## Summary
<!-- One-sentence description -->

## Motivation
<!-- Why is this needed? What problem does it solve? -->

## Acceptance Criteria
- [ ] 
- [ ] 

## Notes
<!-- Mockups, references, edge cases -->
```

### `bug.md`
```markdown
---
name: Bug Report
about: Something isn't working correctly
labels: "type: fix"
---

## Describe the Bug

## Steps to Reproduce
1. 
2. 

## Expected Behavior

## Actual Behavior

## Environment
- Godot version:
- OS:
- Build (main/develop/branch):
```

### `data.md`
```markdown
---
name: Balance / Data Change
about: Tower stats, wave definitions, economy values
labels: "type: data"
---

## What to Change
<!-- Which JSON file(s), which values -->

## Current Values

## Proposed Values

## Reasoning
```

---

## CI Pipeline (Forgejo Actions)

Create `.forgejo/workflows/ci.yml`:

```yaml
name: CI

on:
  push:
    branches: [develop, main]
  pull_request:
    branches: [develop, main]

jobs:
  validate-data:
    name: Validate JSON data files
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check JSON syntax
        run: |
          for f in data/**/*.json; do
            python3 -m json.tool "$f" > /dev/null && echo "OK: $f" || exit 1
          done

  unit-tests:
    name: Run GUT tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Godot 4
        run: |
          wget -q https://github.com/godotengine/godot/releases/download/4.3-stable/Godot_v4.3-stable_linux.x86_64.zip
          unzip -q Godot_v4.3-stable_linux.x86_64.zip
          chmod +x Godot_v4.3-stable_linux.x86_64
          sudo mv Godot_v4.3-stable_linux.x86_64 /usr/local/bin/godot
      - name: Run GUT tests
        run: |
          godot --headless --path . -s addons/gut/gut_cmdln.gd \
            -gdir=res://tests/ -gexit

  export-web:
    name: Export HTML5 build
    runs-on: ubuntu-latest
    needs: [validate-data, unit-tests]
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - name: Install Godot + export templates
        run: |
          wget -q https://github.com/godotengine/godot/releases/download/4.3-stable/Godot_v4.3-stable_linux.x86_64.zip
          unzip -q Godot_v4.3-stable_linux.x86_64.zip
          sudo mv Godot_v4.3-stable_linux.x86_64 /usr/local/bin/godot
          mkdir -p ~/.local/share/godot/export_templates/4.3.stable
          wget -q https://github.com/godotengine/godot/releases/download/4.3-stable/Godot_v4.3-stable_export_templates.tpz
          unzip -q Godot_v4.3-stable_export_templates.tpz -d /tmp/templates
          mv /tmp/templates/templates/* ~/.local/share/godot/export_templates/4.3.stable/
      - name: Export HTML5
        run: |
          mkdir -p build/web
          godot --headless --export-release "Web" build/web/index.html
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: web-build
          path: build/web/
```

---

## PR Template

Create `.forgejo/PULL_REQUEST_TEMPLATE.md`:

```markdown
## Summary
<!-- What does this PR do? -->

## Related Issue
Closes #

## Type of Change
- [ ] Feature
- [ ] Bug fix
- [ ] Balance/data change
- [ ] Chore/refactor

## Testing
- [ ] Ran GUT tests locally
- [ ] Manually tested in Godot editor
- [ ] JSON data validated

## Screenshots / Video
<!-- Optional — paste gameplay clips for UI/visual changes -->
```

---

## Recommended Forgejo Settings

- **Default branch:** `develop`
- **Branch protection on `main`:** require PR + 1 review + CI pass
- **Branch protection on `develop`:** require CI pass
- **Auto-delete head branch after merge:** enabled
- **Squash merges:** enabled for `feature/*` and `fix/*`; merge commits for release PRs to `main`

---

## Typical Feature Workflow

```
1. Create issue with "type: feature" + relevant scope label
2. Branch: git checkout -b feature/<slug> develop
3. Work → commit with conventional commits:
      feat(towers): add Ghost tier-2 upgrade
      fix(economy): correct income calculation on send
      data(waves): adjust wave 15 creep count
4. Open PR → link issue → CI runs
5. Review + merge to develop (squash)
6. When milestone complete → PR develop → main (merge commit)
```