xanarch-td/FORGEJO_WORKFLOW.md

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

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

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

---
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:

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:

## 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)