Skip to content

Clean up repository and add known issues documentation - #18

Open
Morry98 wants to merge 1 commit into
mainfrom
feature/repo-hygiene-docs
Open

Morry98 wants to merge 1 commit into
mainfrom
feature/repo-hygiene-docs

Conversation

@Morry98

@Morry98 Morry98 commented Nov 5, 2026 •

Copy link
Copy Markdown
Owner

Clean up repository and add known issues documentation

What changes

Removed

  • todo.md (410 lines, not in English): a historical implementation plan written before the Redis Streams rewrite. It references code that no longer exists (runner.py:131-153, polling loop, prototype files). Almost everything it proposed is already implemented (worker identity, Redis Streams with consumer groups, reconciliation, leader election, centralized Redis keys, stream-based statistics, priority streams). The only item still open, real retries with a retry limit and a dead-letter stream, is mentioned in one line on the new Known Issues page ("planned"). No Roadmap page was added: a page with a single item would not be useful.
  • usage.md (maintainer notes marked "needs to be moved inside the doc"):
    • uv run mkdocs serve was already in CONTRIBUTING.md; it is now preceded by the missing uv sync --group docs step and followed by uv run mkdocs build --strict.
    • uv run mkdocs gh-deploy is obsolete: docs are deployed by .github/workflows/docs.yml. CONTRIBUTING.md now says so.
    • uv build / uv release are maintainer release steps (and uv release is not a uv command), so they were not moved to the public docs.

README and docs home page

  • Replaced the unverifiable "400% to 500%" and "60% fewer bugs" claims (and the "production-ready" line with its footnote) with factual descriptions. The same claims on docs/docs/index.md were changed the same way.
  • Added a short Status and Guarantees section to the README: what the library does, delivery semantics (at-least-once with best-effort deduplication, not exactly-once), retry behavior, the unauthenticated management router, and links to Known Issues and the issue tracker. The docs home page has the same note as an admonition.
  • The README code example was not changed.

New page: Known Issues (docs/docs/known-issues.md, added to the nav)

Describes the current behaviors with workarounds:

  1. Long-running tasks can be executed again while still running (multi-instance deployments, tasks longer than running_heartbeat_interval * 9). Workarounds: idempotent tasks, raise running_heartbeat_interval, run very long jobs outside the scheduler. Notes that allow_parallel=False does not prevent it.
  2. Failed tasks are not retried before the next cron occurrence; the backoff only delays. Workarounds: in-task retries, POST /tasks/trigger, POST /tasks/reset-retry, monitoring the failure log.
  3. The management router has no authentication. Workarounds: do not expose it, protect it with include_router(..., dependencies=[Depends(...)]) (example included), separate health endpoint for probes, no secrets in kwargs, register=False.

Community files

  • SECURITY.md: private reporting through GitHub Security Advisories (email kept as fallback); supported versions = latest 1.x minor, no backports; honest best-effort response targets (7 days acknowledgement, 14 days assessment); a "Scope" section listing what is not a vulnerability (unauthenticated router by design, attacks that need Redis write access, application task code, non-exploitable dependency CVEs, configuration-induced DoS).
  • CONTRIBUTING.md: docs dependency group and strict build, docs deployment note, Known Issues check before reporting bugs, richer bug report details, CHANGELOG step in the PR checklist.
  • .github/ISSUE_TEMPLATE/bug_report.yml: links to Known Issues and Security Policy; new fields for redis-py version, logs, Config, deployment (instances/workers).
  • .github/ISSUE_TEMPLATE/config.yml: the security contact link now opens the private advisory form.
  • .github/PULL_REQUEST_TEMPLATE.md: strict docs build and CHANGELOG checklist items; bug fixes include a failing-without-fix test.
  • CODE_OF_CONDUCT.md and feature_request.yml were reviewed and left unchanged.

No source code or tests were changed. CHANGELOG.md has no Unreleased section, so no entry was added.

How to verify

  • uv sync --group docs then uv run mkdocs build --strict: passes (no broken links to removed files).
  • pre-commit run --all-files: all hooks pass.
  • grep for Italian words over the repository (excluding .venv, .git, build output): no matches. No other non-English files remain.
  • grep -rn "todo.md\|usage.md": no references left.

Mutations

None: documentation-only change, no behavior to guard with a test.

Notes for the maintainer

  • Private vulnerability reporting must be enabled in the repository settings (Settings → Code security → Private vulnerability reporting) for the "Report a vulnerability" button and the new config.yml link to work.
  • Response targets in SECURITY.md (7/14 days) and the supported versions policy (latest minor only) are proposals; adjust them if they do not match what you can commit to.
  • Classifier: Development Status :: 5 - Production/Stable was not changed. Recommendation: switch to Development Status :: 4 - Beta until the release that fixes the duplicate execution of long-running tasks and the retry behavior (planned for 1.1.2/1.2.0), then move back to 5 - Production/Stable. Reason: the classifier is the first signal users see on PyPI, and today the library can run a task twice or skip a retry under default settings; the Known Issues page mitigates this, but the classifier contradicts it.
  • docs/docs/features.md and docs/docs/learn/architecture.md still claim "exactly once", and configurations.md / architecture.md describe retries that do not happen. They were left out of scope here (documentation accuracy fix tracked separately); the Known Issues page and the README now state the real behavior.
  • Dynamic tasks not propagating between instances and messages for unknown tasks being dropped are also current behaviors but were not listed on the Known Issues page; they can be added if you want the page to be exhaustive.

Text for the GitHub Release note / pinned issue (1.1.1)

Title: Known issues in 1.1.1 and recommended workarounds

FastAPI Task Manager 1.1.1 has the following known behaviors. Fixes are in progress; this issue will be updated when they are released. Full details: https://fastapi-task-manager.morry98.com/known-issues.html

Delivery guarantees. Task execution is at-least-once with best-effort deduplication, not exactly-once. Write tasks that are safe to run twice (upserts, "already done" checks, processed markers keyed by the scheduled time).

1. Long-running tasks can run twice in multi-instance deployments.
With more than one instance or uvicorn worker, a task that runs longer than about 9 × running_heartbeat_interval (27 s by default) can be started again by another worker while the first execution is still running. Starting new instances (rolling deploys, autoscaling) makes it more likely. allow_parallel=False does not prevent it.
Workaround: make long tasks idempotent and raise running_heartbeat_interval so that 9 × its value exceeds your longest task (for example, at least 70 s for tasks up to 10 minutes). Crashed workers will then be detected more slowly.

2. Failed tasks are not retried before the next cron occurrence.
The retry backoff delays the next execution but does not schedule an extra one. A daily task that fails runs again the next day; occurrences inside a backoff window longer than the cron interval are skipped.
Workaround: handle transient errors inside the task, and after fixing the cause run it with POST /tasks/trigger (which also clears the backoff) or clear the backoff with POST /tasks/reset-retry.

3. The management router has no authentication.
Anyone who can reach the router from get_manager_router() can list, create, delete, trigger, disable and enable tasks.
Workaround: do not expose it to untrusted networks and protect it with a FastAPI dependency:

app.include_router(
    task_manager.get_manager_router(),
    prefix="/task-manager",
    dependencies=[Depends(verify_admin)],
)

Do not pass secrets as task keyword arguments, and use register=False on tasks whose functions must not be callable through the API.

Found something else? Open a bug report. Security vulnerabilities: please report them privately as described in SECURITY.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HVysDtCKsBLcXJcnZY2R7S

- Remove todo.md (outdated internal plan, not in English) and usage.md
  (maintainer notes); move the still-useful docs commands to CONTRIBUTING.md
- Replace unverifiable claims in README and docs home page, and add a
  "Status and Guarantees" section describing at-least-once delivery
- Add a Known Issues page with current limitations and workarounds
- SECURITY.md: private reporting via GitHub Security Advisories, supported
  versions, best-effort response targets and scope
- Extend the bug report and pull request templates

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant