QA, Release & Shipping Workflow

This page defines the flow for sending new features to QA, merging branches, and shipping to production. The goal is to keep the release process smooth.

1. Branching

Every feature starts from main:

1. Checkout a new branch from main with name feature-type/feature-name, eg feature/add-new-feature, cosmetic/add-new-feature-2, bug/fix-bug-123, functionality/improve-performance.
2. Do your development work on this branch
3. Push commits regularly

This rule exists so every feature has its own isolated code path.

2. Merging to Staging

When development is complete:

• Create a PR into the staging branch. If staging branch is not yet created, create it first, and create staging environment on Vercel with disabled deployment protection.
• Take care of CodeRabbit Reviews. If CodeRabbit doesn’t trigger for staging, reach out to Dav
• Merge into staging

This is the standard path for any feature that needs QA.

3. Sending Features to QA

After merging your branch into staging, assign one of two statuses:

Status 300 — CRUD Screens

CRUD-type features go directly to Status 300.

Status 500 — Regular Features

Non-CRUD features go to Status 500.

Both statuses mean:

The developer is done and the feature is ready for QA.

Feature in this status should have been tested by developer and is ready for QA. Include:

• link to staging environment
• link to GitHub PR
• link to loom video going through the feature implementation

4. Feedback Loops from QA

QA may return features with feedback.

The return status indicates how the feature moves next.

If QA returns Status 299 or Status 499

Meaning: changes needed, but feature stays in QA flow.

Process:

1. Make changes on the same feature branch
2. Merge into staging again - take care of CodeRabbit Reviews. If CodeRabbit doesn’t trigger for staging, reach out to David
3. Send back for QA following same process as in step 3

No need to merge into main yet.

If QA returns Status 700

Meaning: minor changes needed, no additional review required

Process:

1. Make changes on the feature branch
2. Merge directly into main
3. Then move the feature to Status 900. Provide link to production deployment, link to loom video ready to be sent to client

No need to touch staging.

If QA returns Status 800

Meaning: staging and production need to align before QA finishes.

Process:

1. Merge the feature branch into main
2. Deploy main to staging (update staging from main)
3. Move the feature to Status 900. Provide link to production deployment, link to loom video ready to be sent to client

This ensures staging and production match, and feature is ready to be shipped to client.

5. Final Shipping

Once a feature reaches Status 900:

• It is approved
• It is safe to release
• No more development changes expected

Everything should now be merged to main.

6. Status Summary

7. Notes and Rules

• All work happens on feature branches.
• Never develop directly on staging or main.
• If a feature needs changes, always update the feature branch.
• QA status always determines the next move.

The rule of thumb:

Status controls the workflow, not guesswork.

8. Loom Rules

• Loom videos for status 300 and 500 should serve as explanation to the BAs and developer doing QA how does the feature work, including all technical details.
• Loom videos for status 900 should serve as explanation to the client how the feature works, excluding technical details. This video should show them how they can operate the feature in production.
• Client-facing loom videos should never show data from our own systems (client doesn’t need to see our PM tools, other clients we work on). Clean up the tabs in browser, only minimal required tabs should be open.

9. Summary

• Build on feature branches
• Merge into staging for QA
• Status tells what happens next
• Only ship to main when approved
• Features reach Status 900 only when ready