Development & Deployment Workflow

This guide explains how changes move from a local branch to production for the Tank Safe Portal and documentation. It covers branching, automated previews, Supabase migrations, and rollback options so contributors know what to expect before opening a pull request.

High-level flow

flowchart LR
    A(Developer commits to feature branch) --> B(GitHub PR into development)
    B --> C(Vercel preview build)
    C -->|QA sign-off| D(Merge to development)
    D --> E(Automatic Vercel preview update)
    E --> F(PR from development to main)
    F --> G(Production Vercel build)
    G --> H(Post-merge verification)

Branch strategy

• Feature branches: short-lived branches forked from development. Name them feature/<summary> or docs/<summary>.
• Development: integration branch for day-to-day work. Every push triggers a Vercel preview deployment.
• Main: production branch. Only merges from development land here, ensuring production always reflects a reviewed release candidate.
• Use draft pull requests to surface work-in-progress pipelines without blocking teammates.

Vercel integration

Environment	Trigger	URL scope	Purpose
Preview	Any push to development or a PR targeting development	https://tank-wise-portal-git-dev-*.vercel.app	QA, product review, accessibility checks
Production	Merge to main	https://portal.tanksafe.app	Customer-facing portal
Docs Preview	Same development pushes for the docs repo	https://tanksafe-docs-git-dev-*.vercel.app	Documentation review
Docs Production	Merge to main in docs repo	https://docs.tanksafe.app	Live documentation

Additional notes

• Preview deployments include the PR number in the Vercel dashboard. Use the Inspect tab for logs and request capture.
• Use Vercel "Promote to Production" only in emergencies; the typical flow is always development → main.

Supabase migrations & environment variables

1. Generate migrations with supabase migration new <name> and commit them alongside application changes.
2. During code review, confirm the migration runs cleanly against a linked Supabase project.
3. Before merging development to main, run supabase db push (or let CI do it) so production schema matches the build.
4. Environment variables used by Vercel builds (e.g., VITE_SUPABASE_URL, VITE_SUPABASE_PUBLISHABLE_KEY, VITE_SUPABASE_SERVICE_ROLE_KEY) are managed in Vercel. Keep preview and production values aligned, and rotate keys via Supabase dashboard.

Pull request checklist

• Unit or smoke tests executed locally (if applicable).
• Screenshots or Loom videos attached for UI changes.
• Documentation updated when behaviour or workflows change.
• Supabase migrations validated.
• Changelog entry drafted when the change is user-facing.

Rollback & redeploy

• Preview build issues: push a fix or revert the commit on development; Vercel rebuilds automatically.
• Production issues: in Vercel, select a previous successful deployment and click Rollback. No Git history rewrite is required.
• Coordinate with Supabase if the issue stems from a migration—reverting a schema change may need manual SQL scripts.

Tips for contributors

Keep in mind

• Use npm run lint before pushing to catch CI failures early.
• Supabase service role keys should never ship to the browser bundle; rely on edge functions for privileged actions.
• Reference the Architecture guide for domain context and module ownership when planning larger features.