githubnext / githubnext/ado-aw

docs(site): refresh IR typed-helper docs to builder-struct API

Open
#1,192 0 comments 0 reactions 0 assignees View on GitHub
docs documentation
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.