Inboxintel/docs/discovery/multi-provider/10-git-workflow.md

10 — Git Workflow (Part 11)

Extends ../../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).

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