Public Access
75 lines
2.4 KiB
Markdown
75 lines
2.4 KiB
Markdown
# vikunja-tasks
|
|
|
|
Vikunja task lifecycle beyond `create`: querying status, closing, and
|
|
recovering when the tracker is unreachable.
|
|
|
|
## When to Invoke
|
|
|
|
- Creating, closing, or checking a Vikunja task
|
|
- A spec workflow step needs the task ID or done state
|
|
- `vikunja.oblachno.oblachno.fyi` fails to resolve / times out
|
|
|
|
## Prerequisites
|
|
|
|
- `.env` with `VIKUNJA_TOKEN`
|
|
- Project ID comes from `[tool.devx]` in `pyproject.toml`
|
|
(`DEVX_VIKUNJA_PROJECT_ID`)
|
|
|
|
## Create
|
|
|
|
`make create-task` does **not** forward arguments — call the module:
|
|
|
|
```bash
|
|
.venv/bin/python -m devx.tools.create_task \
|
|
--title "Task title (no DEVX-N prefix)" \
|
|
--description "<h2>Context</h2><p>...</p>"
|
|
```
|
|
|
|
Prints `DEVX-N` + next steps. Title must not include the task-ID
|
|
prefix (auto-merge prepends it; a manual prefix double-prefixes the
|
|
PR title and fails validation).
|
|
|
|
## Query / Close
|
|
|
|
```bash
|
|
# Task details (ID = numeric part of DEVX-N)
|
|
curl -sf -H "Authorization: Bearer $VIKUNJA_TOKEN" \
|
|
"https://vikunja.oblachno.oblachno.fyi/api/v1/tasks/<N>"
|
|
|
|
# Close: mark done
|
|
curl -sf -X POST -H "Authorization: Bearer $VIKUNJA_TOKEN" \
|
|
-H "Content-Type: application/json" -d '{"done":true}' \
|
|
"https://vikunja.oblachno.oblachno.fyi/api/v1/tasks/<N>"
|
|
```
|
|
|
|
Post-merge automation marks the task done when the PR squash-merges —
|
|
manual close is only needed for abandoned/superseded tasks.
|
|
|
|
## Task-ID / Spec Collisions
|
|
|
|
Vikunja IDs can collide with historical spec files (an old task reused
|
|
the number). Convention: preserve the old file as
|
|
`docs/specs/<ID>-<topic>-historical.md`, then write the new spec at
|
|
`docs/specs/<ID>.md`. Check `git log` on the existing spec before
|
|
moving it.
|
|
|
|
## Tracker Unreachable
|
|
|
|
If the Vikunja host fails DNS/TLS:
|
|
|
|
1. Don't block the whole workflow — record the intended task title in
|
|
the spec draft and retry `create_task` before branching.
|
|
2. Never invent an ID — branch/PR titles must match a real task or
|
|
`pre_push_check` / auto-merge validation fails.
|
|
3. DNS failures observed so far were transient; retry after a few
|
|
minutes before escalating.
|
|
|
|
## Common Mistakes
|
|
|
|
- `make create-task -- --title ...` — args are dropped; use the module
|
|
call above (forwarding fix is S11 scope).
|
|
- Including `DEVX-N:` in the task title — double prefix breaks
|
|
auto-merge.
|
|
- Closing a task whose PR is still open — auto-merge's post-merge
|
|
step handles the close; manual close confuses the audit trail.
|