Contributing¶

Contributions should keep citizen flows clear, state recoverable, and integrations secure. Work from a focused branch and avoid mixing generated files, credentials, and unrelated refactors into the same change.

Development workflow¶

Sync the intended base branch.
Create a short-lived branch.
Make the smallest coherent change.
Add or update tests and documentation.
Run backend, Flutter, and documentation checks that apply.
Review the diff for secrets and generated artifacts.
Open a pull request that explains behavior, risk, and verification.

Suggested commit style:

feat(journeys): persist milestone completion
fix(auth): reject expired identity assurance
docs(api): document journey error responses

Pull request checklist¶

[ ] Citizen-visible behavior is explained.
[ ] API contracts remain backward compatible or the migration is documented.
[ ] Authorization and ownership checks are tested.
[ ] Loading, empty, error, and retry states are handled.
[ ] No secret, token, personal data, private key, or restricted provider text is included.
[ ] flutter analyze, flutter test, and relevant backend tests pass.
[ ] mkdocs build --strict passes for documentation changes.
[ ] Screens remain usable with text scaling and narrow widths.

Coding principles¶

Prefer typed contracts over loose maps.
Keep HTTP and provider concerns out of UI widgets.
Keep business rules out of FastAPI route functions.
Make transitions idempotent where requests may be retried.
Preserve existing user state during schema or workflow changes.
Log stable internal identifiers, not sensitive payloads.

Documentation style¶

Write for an engineer who is new to eAkto. Lead with the purpose, give a safe runnable example, state preconditions, and explain failure modes. Use YOUR_VALUE or environment variable names—never a real credential.