Files

T

Thomas SharedInboxandClaude Sonnet 4.6 f0c0eeb9a4 docs(agents): add explicit fgj commands for issue label transitions

Makes the InProgress-first rule harder to skip by including the exact
command to run, so there is no ambiguity about how or when to do it.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-14 18:49:00 +02:00

2.5 KiB

Raw Blame History

SharedInbox — Development Guide

Codeberg

We use Codeberg: https://codeberg.org/guettli/sharedinbox/

CLI tool fgj is available to query issues/PRs/actions.

Issue Label Workflow

We use issues, follow this label state machine:

State/Ready — Issue is available to pick up
State/InProgress — Set this when you start working on an issue
State/Question — Set this when you hit a blocker or need clarification

List open issues ready to pick up:

fgj issue list --json --state open | jq '[.[] | select(.labels[].name == "State/Ready")] | .[] | {number, title, html_url}'

Rules:

Never start work on an issue without State/Ready
Switch State/Ready → State/InProgress as your first action when picking up an issue — before reading any code:
```
fgj issue edit <NUMBER> --remove-label "State/Ready" --add-label "State/InProgress"
```
If blocked, replace current state label with State/Question and leave a comment explaining the blocker
When done and CI is green, close the issue:
```
fgj issue close <NUMBER>
```

Code conventions

Avoid else, use "early return".

Drift (DB)

Schema in lib/data/db/database.dart.
After any schema change run: dart run build_runner build --delete-conflicting-outputs
Generated database.g.dart is committed — do not hand-edit it.

enough_mail

Standard pub dependency (enough_mail: ^2.1.7 in pubspec.yaml) — not vendored.
IMAP client helpers are in lib/data/imap/imap_client_factory.dart.

Running

Flutter build dependencies (libgtk-3-dev, libepoxy-dev, libsecret-1-dev, etc.) are installed via apt — see the Flutter Linux docs. The nix dev shell provides only tools: task, fvm, stalwart-mail.

Enter the nix dev shell first: nix develop

# Code generation (must run after schema changes)
task codegen

# Desktop
task run

# Tests
task test

Adding a screen

Create lib/ui/screens/my_screen.dart.
Add a GoRoute in lib/ui/router.dart.
No separate ViewModel file needed — use ConsumerWidget / ConsumerStatefulWidget directly with Riverpod providers.

Continuous Integration (CI)

Strategy: "Thin CI, Heavy Taskfile".
Execution: CI must only invoke task commands (e.g., nix develop --command task check). All environment setup is handled by Nix (flake.nix), and all task orchestration is handled by Taskfile.yml.
The cli-tool fgj is available to query/wait for CI.

2.5 KiB Raw Blame History