E Event

WORKFLOW — How FLA is built and versioned

Applies to every session and every feature. If you skip a step, history loses value.

The loop (per feature)

Plan ──► docs/SRS.md (new/updated use case + FR/BR refs)
     ──► docs/WORKFLOWS/<flow>.md (create/update the step flow)
     ──► implement (src/Modules/<Module>, migrations if needed)
     ──► verify (lint + run through the flow)
     ──► CHANGELOG.md (unreleased section) + ROADMAP.md (status) + TODO.md (state/next)
     ──► git add -A && commit (conventional message)
     ──► (milestone) annotated tag + move CHANGELOG items into new version section

Good saves, always: commit after each meaningful step — never end a session with uncommitted work. The user asked explicitly: keep saving things.

Git conventions

  • Single local branch: master. No remote (local versioning) unless the owner asks.
  • Conventional Commits:
    • feat(module): … new capability · fix(module): … · docs: … · chore: …
    • refactor: … · style: … · test: … · perf: …
  • Milestone tags (annotated, e.g., git tag -a v0.2.0 -m "v0.2.0 — admin core & branding"):
    • v0.1.0 docs+scaffold → v0.2.0 admin core → … → v1.0.0 launch.
  • Never commit: .env, keys, dumps, storage/cards|uploads|logs/* (see .gitignore).
  • Commit identity: use the owner's git identity; do not rewrite history.

Documentation rules

You changed…Update…
Any feature/flowdocs/SRS.md use case + docs/WORKFLOWS/<flow>.md
Scope/plan of a milestoneROADMAP.md (status markers)
Anything (always)CHANGELOG.md → [Unreleased]
State/next/answers to questionsTODO.md (before ending the session)
Build/test/run instructionsHELP.md
Rules on this pageWORKFLOW.md itself

Docs render live at /docs — no build step needed.

Versioning

  • SemVer; composer.json#version mirrors the tag.
  • CHANGELOG sections: Added | Changed | Deprecated | Removed | Fixed | Security.
  • At tag time: create [<version>] — <date> heading, move items from [Unreleased].

Coding conventions

  • Plain PHP 8.3; declare(strict_types=1); at top of every file.
  • PSR-4 App\ → src/; modules self-contained in src/Modules/<Name>

(Controller, views live centrally in views/<module>/, migrations in database/migrations/).

  • SQL via PDO prepared statements only. Output escaped via e().
  • Feature flags from feature_toggles; branding/weights from settings (never hardcode).
  • Keep NFR-08: everything works in mock mode without external keys.

Definition of done (milestone)

  1. Milestone scope implemented + verified end-to-end.
  2. SRS/workflows updated; ROADMAP status moved; TODO state accurate.
  3. CHANGELOG version section written.
  4. Single/tagged release commit, e.g., chore(release): v0.2.0 + annotated tag.