cesnimda
4ce2df0a2b
CI / backend (push) Successful in 52s
CI / frontend (push) Successful in 14s
Deploy Staging / deploy (push) Successful in 18s
CI / backend (pull_request) Successful in 52s
CI / frontend (pull_request) Successful in 15s
Security / secrets (push) Successful in 4s
Security / dependencies (push) Successful in 55s
Security / secrets (pull_request) Successful in 4s
Security / dependencies (pull_request) Successful in 54s
51 lines
3.2 KiB
Markdown
51 lines
3.2 KiB
Markdown
# 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).
|