# 10 — Git Workflow (Part 11)

Extends [../../WORKFLOW.md](../../WORKFLOW.md) for multi-phase, multi-provider work. The
core idea: **feature flags decouple *merging* from *activating*, which makes every
integration safe to land and trivial to roll back.**

## Branching per phase
| Phase | Milestone | Branches |
|-------|-----------|----------|
| 1 Provider abstraction + Google | `v1.x` | `epic/provider-platform` → `feature/email-provider-interface` · `feature/gmail-adapter` · `feature/oauth-login-users` |
| 2 Microsoft | `v1.x` | `feature/outlook-provider` · `feature/microsoft-oauth` |
| 3 Unified model + sync | `v1.x` | `feature/normalised-email-model` · `feature/sync-orchestrator` · `feature/data-migration` |
| 4 Settings | `v1.x` | `feature/settings-store` · `feature/feature-flags-engine` |
| 5 Admin | `v1.x` | `feature/admin-api` · `feature/admin-ui` · `feature/audit-log` |
| 6 AI layer | `v1.x` | `feature/ai-abstraction-ext` · `feature/ai-analyzers` · `feature/ai-flag-gating` |
- `feature/* → develop` (squash), `develop → main` (merge commit) — as established. Epics are
  tracked by milestone/label; features integrate continuously (no long epic branch).

## PR structure per provider integration
Each provider is a self-contained PR set that lands **dark**:
1. **Adapter PR** — `IEmailProvider` impl + normaliser + unit tests (mocked provider).
2. **Auth PR** — OAuth login/link for that provider.
3. **Enablement PR** — register in `ProviderFactory` + seed `provider.<x>` flag **OFF**.
4. **Activation** — flip the flag on in staging → verify end-to-end → roll out in prod.
- **PR checklist adds:** provider behind a flag (off by default) · normaliser tests · token
  encryption verified · no Domain leakage · docs updated.

## Feature flags prevent breaking changes
- Merge = code present but **inert** until its flag is on. So half-finished providers/AI can
  live on `main` safely; CI stays green; no long-lived divergence.
- AI ships behind `ai.*`; providers behind `provider.*`; risky changes behind their own flag.

## Rollback strategy (per provider / per feature)
| Level | Action | Speed |
|-------|--------|-------|
| **Flag** (first resort) | Admin flips `provider.<x>` / `ai.<x>` **off** | **Instant, no deploy** — feature disappears, existing data untouched |
| **Deploy** | Redeploy the previous **tag** (`vX.Y.Z-1`) | Minutes (pipeline) |
| **Revert** | `git revert` the PR → PR → merge → deploy | Minutes–hours |
| **Data** | Provider accounts are isolated; disabling a provider **pauses** its sync — no destructive change to migrate back | Safe by design |
- Because providers are isolated and flag-gated, a bad integration **never blocks the others**
  and never requires a risky data rollback.

## Release milestones
- Cut a tag when a phase reaches its exit criteria (`deploy-prod.yml` fires on `v*`).
- Suggested: `v1.1` provider platform + Google · `v1.2` +Outlook · `v1.3` unified sync ·
  `v1.4` settings+admin · `v1.5` AI layer — folded into the blueprint roadmap ([../09](../09-roadmap.md)).

## Docs alongside code
Every feature PR updates the relevant `multi-provider/*` doc + `CHANGELOG.md`; on approval the
design docs graduate into living `docs/` references (provider system, settings, admin, security).