docsy(v2): open the quickstart with a run that needs no files - #1572
Merged
Conversation
ppiegaze
requested review from
EngHabu,
cosmicBboy,
kumare3 and
samhita-alla
as code owners
September 3, 2026 10:35
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The new output snippet is formatted as bash and appears to mix actual CLI output with instructional text, which can mislead readers and should be corrected before merge.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR updates the Quickstart documentation to let readers run a built-in Flyte example immediately (without creating any files), then optionally points Union users to --tracked so the local run can appear in the console, and it refines wording around what @env.task implies about execution context.
Changes:
- Adds a new “Run something straight away” section using
flyte run --local hellobefore any file authoring. - Adds a Union-only note introducing
--trackedand linking to the tracked-local-runs docs. - Updates the
@env.taskexplanation from “run remotely” to “can run on a cluster”.
File summaries
| File | Description |
|---|---|
| content/user-guide/get-started/quickstart.md | Inserts an immediate no-files run path, adds Union-gated tracked-run guidance, and tweaks task execution wording for accuracy. |
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+67
to
+71
| ```bash | ||
| Using the built-in example from /tmp/flyte-hello-<user>/task/hello.py | ||
| Copy it into your own project to start editing. | ||
| Completed Local Run Outputs: ActionOutputs(o0=14.0) | ||
| ``` |
GHA build & deploy previewBuilt by
Updated automatically on every push. |
ppiegaze
marked this pull request as draft
September 3, 2026 16:13
ppiegaze
added a commit
that referenced
this pull request
Sep 4, 2026
docs: bump unionai-examples to a94a9f1f7 for temperatures.py Pointer-only. Brings in unionai-examples#310, which adds v2/user-guide/getting-started/temperatures.py, the file the reworked quickstart (#1572) includes. Kept separate from the content PR per the submodule-hygiene rule: a pointer bump never rides in a content change. Claude-Session: https://claude.ai/code/session_017CJ89R9ri86y11FFhPdVJV Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com> Co-authored-by: docsy <docsy@union.ai> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
The quickstart's first instruction was to write a file. Before a reader has any feel for what a task looks like, they need a TaskEnvironment, a decorator, a main, and a guess at how to invoke it. That is a lot of blank page for someone who wants to see the thing work once. `flyte run --local hello` removes it. The SDK carries the example, writes it to a scratch directory, runs it, and prints the path, so the next step is a copy rather than "now write your own from the docs". It shipped in flyte-sdk#1496 on 2026-09-01 and is already in the pinned CLI reference. For Union readers the section also points at `--tracked`, which is the whole payoff of a signup with no cluster attached: the run executes on your machine and still appears in the console under Tracked Runs. That note is variant-gated, since tracked runs are Union-only. Verified by running both commands on flyte 2.6.13 in an empty directory rather than by reading the CLI source. The output block is real output. Also fixes one line in the same file that the DOC-1326 rule makes wrong: "@env.task turns Python functions into tasks that run remotely" names the execution model with a cluster-location word. Now "that can run on a cluster". Called out separately because the rest of that phrase family is DOC-1536, not this PR -- but leaving a known error in a file being edited is worse than the small scope. Co-Authored-By: docsy <docsy@union.ai> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017CJ89R9ri86y11FFhPdVJV Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>
…built-in
Peeter's call: the built-in `hello` is the see-it-work step, and the
reader's first real file should be a different program with a
different name. Until now the quickstart's hello.py was the same
program as the SDK's built-in with different identifiers, so a reader
retyped what `flyte run --local hello` had just written to a scratch
directory, and `hello` next to `hello.py main` on one page invited
confusion.
temperatures.py (unionai-examples#310) converts a list of readings with
flyte.map and returns the hottest: same lessons, unmistakably different
code, names and output. The output block is real output from running
it, o0=75.7.
Also: the run-it warning said "when running remotely", the phrasing
DOC-1326 retired. Now "when running on a cluster".
Depends on unionai-examples#310 merging and the examples submodule
pointer being bumped in its own PR; the {{< code >}} include cannot
resolve on CI until then, so this goes back to draft.
Co-Authored-By: docsy <docsy@union.ai>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017CJ89R9ri86y11FFhPdVJV
Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>
ppiegaze
marked this pull request as ready for review
September 4, 2026 07:25
ppiegaze
force-pushed
the
docsy/v2-quickstart-hello
branch
from
September 4, 2026 07:25
340749c to
37989eb
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The quickstart's first instruction was to write a file. This opens with a run that needs none, then has the reader write a different file of their own.
Why
Before a reader has any feel for what a task looks like, the quickstart asked for a
TaskEnvironment, a decorator, amain, and a guess at how to invoke it.flyte run --local helloremoves that blank page: the SDK carries the example, runs it, and prints the path. Shipped in flyte-sdk#1496 on 2026-09-01 and already in the pinned CLI reference.The second decision in this PR
The quickstart's
hello.pywas the same program as the SDK's built-in, differing only in identifiers. So after the first step, the reader would retype what the SDK had just written to a scratch directory — andhellobesidehello.py mainon one page is a naming collision waiting to happen. (The scratch path is per-user, platform-dependent and rewritten on every run, so "copy the printed file" is a weak step too.)Peeter's call: the built-in is the see-it-work step; the first real file is a different program with a different name.
temperatures.pyconverts readings withflyte.mapand returns the hottest. Same lessons, unmistakably different code, names and output.What's here
--tracked— the payoff of a signup with no cluster attached. Links to the section merged in docsy(v2): document tracked local runs (--tracked / --tracked-strict) #1462.temperatures.py, with aflyte.mapbullet added to "Here's what's happening", and "Run it" showingflyte run --local temperatures.py hottestwith its real output (o0=75.7, rounded in the task because the raw float was75.74000000000001).Verification
make distclean on both variants against examples commit75914a6;check-subpage-cardsOK.--trackednote inuniononly;hellosection andtemperatures.pyin both.hello.pyon the page is exactly one: the scratch path in the built-in's printed output, which is correct.Worth a look on review
The two TUI screenshots under "See the results" were captured from the old
hello.pyrun and will showhello_env/main. Still valid illustrations of the TUI, but a recapture with thetemperaturesrun would match the page. Not done here.hello.pyinunionai-examplesis now unreferenced by the quickstart. Its fate is a follow-up in that repo.— docsy · automated docs agent
🤖 Generated with Claude Code
https://claude.ai/code/session_017CJ89R9ri86y11FFhPdVJV