Development Workflow

This document defines the default path from idea to released change.

For branch policy, see branching.md. For release execution, see release-process.md. For task quality gates, see CHECKLISTS.md.

Workflow Overview

flowchart LR
    Idea["Idea, bug, or feedback"]
    Clarify["Clarify scope"]
    Plan["Plan or ADR"]
    Implement["Implement"]
    Validate["Validate"]
    Review["Review"]
    Merge["Merge"]
    Release["Release"]
    Learn["Update docs/checklists"]

    Idea --> Clarify
    Clarify --> Plan
    Plan --> Implement
    Implement --> Validate
    Validate --> Review
    Review --> Merge
    Merge --> Release
    Release --> Learn

1. Clarify Scope

Before implementation:

restate the objective in engineering terms;
identify affected public, admin, backend, database, or deployment surfaces;
confirm acceptance criteria and non-goals;
identify security, authorization, migration, data-loss, or live-production risk;
ask concise questions when ambiguity affects important behavior.

2. Inspect Existing Context

Read the relevant source and docs before editing:

PROJECT.md for runtime and product facts;
ARCHITECTURE.md for boundaries;
CONVENTIONS.md for coding standards;
DECISIONS.md for durable trade-offs;
../DESIGN.md for UI work;
feature plans such as workflow-feedback-plan.md when the task builds on planned product feedback.

3. Plan The Change

Use a lightweight plan for non-trivial changes. Create or update an ADR when the change affects:

architecture style or module boundaries;
data ownership or public contracts;
authentication, authorization, or security posture;
deployment strategy, migrations, or long-term operating cost.

4. Implement

Implementation expectations:

keep changes focused and reviewable;
follow existing frontend/backend patterns;
split large Vue surfaces into smaller components or composables;
keep backend/admin data authoritative for public behavior;
avoid unrelated refactors unless needed for the requested change;
preserve user changes in a dirty worktree.

5. Validate

Default validation:

cd frontend
npm run build

cd ..
dotnet build Backend/Backend.csproj --configuration Release
git diff --check

For core nomination, category, voting, winner, permission, or archive changes, also run the repeatable smoke path in end-to-end-smoke.md.

Add targeted validation by risk:

API checks for backend behavior;
authenticated checks for admin/team/permission changes;
browser checks for visible UI changes;
responsive geometry checks for layout work;
database health and migration checks for schema changes;
live checks only for release or explicitly live-scoped work.

When frontend and backend are both actively used for local verification, keep them running as a pair or shut both down together.

6. Review

Review should answer:

Does the change solve the stated problem?
Does it preserve backend/admin truth?
Is authorization enforced at the trusted boundary?
Are migrations and deployment risk understood?
Are docs and validation sufficient for the risk?

7. Merge And Release

main is the production deployment branch. Pushes to main run CI and deploy when the workflow conditions match. Follow release-process.md.

8. Learn

After meaningful releases, regressions, or repeated review feedback:

update docs or checklists;
add or update ADRs;
add regression coverage when practical;
record follow-up work where the repo exposes an operational or test gap.

3.7 KiB Raw Permalink Blame History