Development Workflow
Every change to the TABS website follows a structured path from idea to production. This is not accidental — for a research project that handles survey data and analytics, we need to know that every deployed change has been tested, reviewed, and verified. This page documents our entire development pipeline.
Issue → PR → Merge → Deploy
No code reaches production without passing through this pipeline:
GitHub Issue
Every change starts as a tracked issue. Bug reports, feature requests, and documentation updates all get an issue number for traceability.
Feature Branch
A branch is created from main using conventional naming: feat/, fix/, docs/, or chore/.
Pull Request
A PR is opened referencing the issue. This triggers CI and automated code review. The PR template includes an accessibility checklist.
CI Checks (7 total)
All checks must pass before merge. See details below.
Squash Merge
PRs are squash-merged into main, keeping the commit history clean with one commit per feature. The feature branch is automatically deleted.
Automatic Deploy
Merging to main triggers the deploy workflow, which builds the static site and pushes it to GitHub Pages. The site is live within minutes.
CI Pipeline: 7 Checks
Every pull request runs through seven automated checks before it can be merged:
| Check | What It Does | Typical Time |
|---|---|---|
| Test & Build | Prettier format check, ESLint, Jest unit tests (including jest-axe accessibility), static build | ~2 min |
| E2E Shard 1/4 | Playwright browser tests split across four parallel shards — logo rendering, image loading, navigation, page content verification | ~2 min each |
| E2E Shard 2/4 | ||
| E2E Shard 3/4 | ||
| E2E Shard 4/4 | ||
| CodeQL (JavaScript/TypeScript) | GitHub's semantic code analysis for security vulnerabilities in application code | ~1 min |
| CodeQL (Actions) | Security analysis of GitHub Actions workflow files | ~40 sec |
Additionally, Lighthouse CI runs on merges to main, scoring performance, accessibility, best practices, and SEO.
Merge Queue
The repository uses GitHub's merge queue to prevent integration failures when multiple PRs are approved around the same time. Instead of merging immediately, PRs enter a queue where GitHub creates a temporary merge commit combining the PR with the current state of main and any PRs ahead of it in the queue.
The full CI suite runs against this temporary merge commit. If any check fails, the offending PR is removed from the queue and the others re-test. This guarantees that what merges into main has been tested against the actual code it will sit alongside, not just the state of main when the PR was opened.
This is especially valuable for a statically exported site — a broken build in the merge queue stops the deploy before it ever reaches GitHub Pages.
Automated Operations
Beyond CI/CD, GitHub Actions runs several scheduled workflows that keep the project data current:
Daily GA Report
Runs at midnight UTC. Fetches Google Analytics data, generates a report artifact, updates public impact statistics, and emails a summary to stakeholders.
Qualtrics Metrics Update
Periodically fetches survey question count and response counts from the Qualtrics API, keeping the homepage statistics current.
Prolific Data Collection
Weekly workflow (Mondays, 9 AM UTC) that collects participant study data from Prolific and stores it as a workflow artifact.
Dependabot
Automated dependency updates for npm packages and GitHub Actions. Security patches are flagged for immediate attention.
Living Documentation
Documentation is not an afterthought — it is a first-class part of every change. When a feature is added, its documentation is updated in the same PR. This includes:
- CHANGELOG.md — tracks every release and notable change
- Instruction files — AGENTS.md, CLAUDE.md, GEMINI.md updated when architecture changes
- Sitemap — maintained in src/app/sitemap.ts; new routes are added manually to keep SEO coverage complete
- Community health files — CODE_OF_CONDUCT, CONTRIBUTING, SECURITY, SUPPORT maintained alongside code
This "living documentation" approach means the project remains understandable to new contributors — human or AI — at any point in time.
This workflow is itself documented in AGENTS.md, which AI agents read before every session.