Skip to content

docs(docs/ai-coder): add deprecation notice to Coder Tasks pages#24831

Merged
mattvollmer merged 3 commits into
mainfrom
dfraley/codagt-157-tasks-deprecation-header
May 5, 2026
Merged

docs(docs/ai-coder): add deprecation notice to Coder Tasks pages#24831
mattvollmer merged 3 commits into
mainfrom
dfraley/codagt-157-tasks-deprecation-header

Conversation

@david-fraley
Copy link
Copy Markdown
Collaborator

Adds a deprecation warning callout to the top of the main Coder Tasks docs page (docs/ai-coder/tasks.md).

The message reads:

Beginning June 2026, Coder Tasks will be deprecated. Support for Tasks will be maintained on Coder's ESR release and through Coder v2.36. After v2.36, support for Tasks will only be on our 12-month ESR release for Coder Premium Customers.

Uses the existing > [!WARNING] admonition pattern already used for deprecations elsewhere in the docs (e.g. docs/ai-coder/ai-gateway/mcp.md).

Linear: CODAGT-157


This PR was opened by Coder Agents on @davidfraley's behalf.

@github-actions
Copy link
Copy Markdown

Docs preview

📖 View docs preview

david-fraley added a commit that referenced this pull request Apr 30, 2026
…sks walkthrough

Removes the optional 'Get Coder Tasks Running' section that walked users
through pulling the tasks-docker template from the Registry and creating
a Coder Task. The main flow already uses the original Docker Containers
starter template, so removing the Tasks epilogue restores the original
non-task quickstart and avoids steering new users at a feature that is
about to be deprecated (PR #24831 adds the deprecation notice).

In its place, the 'What's Next?' section now links to Coder Agents
getting started, the chat interface and API for delegating development
work to coding agents in the Coder deployment.

Also drops the orphaned 'Tasks' row from the cooking-analogy table, the
optional task line in the 'What You'll Build' checklist, and the
'Claude Code in the background' aside in the lead paragraph. Deletes
the now-unreferenced quickstart-tasks-background-change.png screenshot.

Linear: CODAGT-157
david-fraley added a commit that referenced this pull request Apr 30, 2026
Reframe the section so the deprecation drives the migration. Calls
out the v2.36 cutoff and the Premium-only ESR fallback that PR #24831
adds to the Tasks page, instead of leaving the choice as 'if you are
adopting Coder Agents'.

Linear: CODAGT-157
Refs: #24831

\u003e Coder Agent generated this commit on @david-fraley's behalf.
Copy link
Copy Markdown
Collaborator Author

Re-checked the wording with @david-fraley (the release team). Confirmed:

  • June 2026 deprecation date is correct.
  • Support maintained on ESR and through Coder v2.36 is correct.
  • Post-v2.36, support only on the 12-month ESR release for Coder Premium Customers is correct.

No wording changes needed.

The accuracy review also flagged that other Tasks-deep-dive pages (tasks-core-principles.md, github-to-tasks.md, custom-agents.md, agent-compatibility.md) and the ## Agents with Coder Tasks section in docs/ai-coder/index.md lack the same warning. Tracking that as follow-up work; not blocking this PR.

This is Coder Agents responding on @david-fraley's behalf.

@mattvollmer
Copy link
Copy Markdown
Contributor

While more verbose, I recommend being more explicit in a few areas to help avoid confusion. We should also position Agents as the alternative. For example:

Starting June 2, 2026, Coder Tasks will move to a 12-month Extended Support Release (ESR) for Premium customers.

Tasks will be removed from new Coder releases beginning with v2.37 (September 1, 2026) and will only be available via the ESR during the support period.

We recommend transitioning to [Coder Agents](/docs/ai-coder/agents), the long-term replacement.

@mattvollmer
Copy link
Copy Markdown
Contributor

Additionally, we might consider adding this to all /tasks/* child pages in case they receive direct traffic.

mattvollmer added a commit that referenced this pull request May 4, 2026
…#24929)

Updates `docs/ai-coder/index.md`, `docs/ai-coder/best-practices.md`, and
`docs/ai-coder/ai-governance.md` to point readers at Coder Agents and
the AI Governance Add-On instead of Coder Tasks and Agent Firewall
(CODAGT-157).

## Changes

- `docs/ai-coder/index.md`:
- Rename `## Agents with Coder Tasks` to `## Coder Agents`. Drop the
Devin / ChatGPT Codex name-drops and the Tasks pitch. New copy points at
`./agents/index.md`, names the agent loop in the control plane, and
notes that workspaces can be completely network isolated. Image swapped
from `tasks-ui.png` to `agents-hero-image.png` (the hero shot added in
#24915).
- Replace the `## Secure Your Workflows with Agent Firewall` section
with `## Govern AI activity with the AI Governance Add-On`. The new
section opens with adoption-first framing (visibility, guardrails, cost)
and links to `./ai-governance.md`, with bulleted callouts for AI
Gateway, Agent Firewall, and the expanded Agent Workspace Build
allowance the add-on bundles.
- `docs/ai-coder/best-practices.md`:
- In the use-case table, swap `[Tasks](./tasks.md)` to `[Coder
Agents](./agents/index.md)` for the developer-led-investigation and
prototyping rows, and swap the "Tasks API *(in development)*" cell to
`[Coder Agents API](./agents/chats-api.md)` for the background-jobs row.
Retitle the Security section link from "securing agents with Coder
Tasks" to "securing AI agents" since `security.md` does not actually
mention Tasks. Re-ran `markdown-table-formatter` to repad column widths.
- In `## Provide Agents with Proper Context`, add a paragraph describing
how context is provided in Coder Agents (admin-configured system
prompts, centrally registered MCP servers, and skills shipped from repos
or templates under `.agents/skills/`), with a transition line clarifying
that the existing Memory and Tools subsections cover BYO-agent patterns.
- `docs/ai-coder/ai-governance.md`: drop the "Additional Tasks Use (via
Agent Workspace Builds)" bullet from the intro feature list and the
"Expanding the use of Coder Tasks for AI-driven background work" bullet
from the audience list. The `## How Coder Tasks usage is measured`
section and the rest of the Tasks-related prose on this page are
intentionally left for a follow-up PR.

## Notes for the reviewer

- The `[Coder Agents API](./agents/chats-api.md)` link in
`best-practices.md` will need to be retargeted if #24830 (which replaces
`agents/chats-api.md` with auto-generated `reference/api/chats.md`)
lands first.
- This is the first slice of the Tasks-references audit. Remaining files
(`tasks-core-principles.md`, `tasks-lifecycle.md`, `tasks-migration.md`,
`cli.md`, `github-to-tasks.md`, `agent-compatibility.md`, the rest of
`ai-governance.md`, `custom-agents.md`,
`ai-gateway/clients/claude-code.md`, `manifest.json`,
`reference/api/tasks.md`, the `task*` CLI references, the ESR upgrade
guide, `feature-stages.md`, `workspace-scheduling.md`,
`shared-workspaces.md`) will land in follow-up PRs against the same
Linear ticket. Open PRs #24831, #24833, and #24841 cover separate slices
and do not touch any file in this PR.
- Validation: `markdownlint-cli2`, `markdown-table-formatter`,
`scripts/check_emdash.sh`, and `make pre-commit-light` all pass.

PR generated with Coder Agents.
Comment thread docs/ai-coder/tasks.md Outdated
david-fraley and others added 2 commits May 5, 2026 13:21
… tasks pages

Integrates Matt's review feedback:
- Reword deprecation notice to be more explicit about dates and versions.
- Position Coder Agents as the recommended alternative.
- Add the deprecation warning to all tasks-related child pages for
  direct traffic visitors.
@mattvollmer mattvollmer changed the title docs(docs/ai-coder/tasks.md): add deprecation notice to Coder Tasks page docs(docs/ai-coder): add deprecation notice to Coder Tasks pages May 5, 2026
@mattvollmer mattvollmer merged commit 81109e1 into main May 5, 2026
29 of 30 checks passed
@mattvollmer mattvollmer deleted the dfraley/codagt-157-tasks-deprecation-header branch May 5, 2026 15:04
@github-actions github-actions Bot locked and limited conversation to collaborators May 5, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants