githubnext / githubnext/ado-aw
docs(site): refresh IR typed-helper docs to builder-struct API
- Dominant language
- Rust
- Stars
- 23
- Forks
- 8
- Avg merge
- 4d 9h
- Merged PRs (30d)
- 22
Description
## Problem
The published **site IR docs** still document the old free-function task-helper API, which no longer exists in the code. After the typed-task refactor, helpers moved from `src/compile/ir/tasks.rs` (a single file of free functions like `copy_files_step()`, `nuget_command_step()`) to **builder structs** under `src/compile/ir/tasks/` (one file per task, e.g. `CopyFiles::new(..).into_step()`).
The following site docs are stale and reference the removed API and the deleted `tasks.rs` file:
- `site/src/content/docs/guides/extending.mdx` — "The full set of typed helpers lives in `src/compile/ir/tasks.rs`" + free-function example.
- `site/src/content/docs/reference/ir.mdx` — `tasks.rs` bullet + the entire "Typed task helpers" table (lists `copy_files_step(..)`, `nuget_command_step(command)`, `powershell_file_step(..)`, etc.).
## Scope
- Update both `.mdx` files to describe the builder-struct API (`Task::new()` + typed chained setters + `.into_step()`), per the convention in `src/compile/ir/tasks/mod.rs`.
- Replace the free-function helper table with the current builder structs, and refresh the example.
- Fix references to `src/compile/ir/tasks.rs` -> `src/compile/ir/tasks/` (directory, one file per task).
- Ensure the docs cover the full current set of builders in `src/compile/ir/tasks/`, including the recently-requested `PublishPipelineArtifact@1`, `DownloadPipelineArtifact@2`, and `DeleteFiles@1` (the additions attempted in #1079).
## Context
- Surfaced while reviewing the open agentic-workflow PR backlog.
- #1079 attempted to extend the stale table and was closed in favor of this full refresh.
- The `docs/ir.md` / `docs/extending.md` markdown sources may need the same treatment; check them alongside the site mdx (the big in-flight PR #1096 also touches `docs/ir.md`, so coordinate to avoid conflicts).
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with src/compile/ir/tasks/mod.rs and the builder files under src/compile/ir/tasks/ to inventory the current API. Update site/src/content/docs/guides/extending.mdx and site/src/content/docs/reference/ir.mdx, then check docs/ir.md and docs/extending.md for matching stale references. Done means the examples and table describe the builder-struct API and include all current builders, including PublishPipelineArtifact@1, DownloadPipelineArtifact@2, and DeleteFiles@1; coordinate around PR #1096.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 70/100