Commands v3 Documentation #3095

jasondaming · 2025-10-03T04:38:46Z

I added a bunch of stuff in here. Maybe some of it is too verbose? The idea was basically that Commands v3 could almost completely stand on its own.

source/docs/software/commandbased/commands-v3/command-compositions-v3.rst

SamCarlberg

First pass, still a lot to cover. Generally, I'd like sections to have more detail that just one or two sentences, particularly for things like parent/child commands and nested triggers. The LLM also seems to be conflating some v2 and v3 APIs (and outright hallucinating a few others)

We should also have a conversation about suggested project structure, since the Robot/RobotContainer split does a poor job of separating concerns

SamCarlberg · 2025-10-03T12:57:13Z

source/docs/software/commandbased/commands-v3/migration-from-v2.rst

+
+   Command driveWithTimeout = Commands.race(
+     drivetrain.driveToPose(pose),
+     Commands.waitSeconds(3.0)


Is there a better example than racing with a wait command? That's more idiomatically written using withTimeout. Maybe play an LED pattern instead?

I replace it with an LED while doing action example. Is the thinking that this works in place of deadline or do we have that too and I missed it?

SamCarlberg · 2025-10-03T12:59:41Z

source/docs/software/commandbased/commands-v3/migration-from-v2.rst

+
+   * - Commands v2
+     - Commands v3
+   * - ``edu.wpi.first.wpilibj2.command.*``


btw, v2 is moving to the org.wpilib.commands2 package in 2027

I think it now hast it right in anticipation for this but it will be easier once we get things moved but I know that is a huge PR

SamCarlberg · 2025-10-03T13:04:08Z

source/docs/software/commandbased/commands-v3/migration-from-v2.rst

+   controller.a().onTrue(Commands.runOnce(() -> intake.extend()));
+   controller.b().whileTrue(new RunCommand(() -> intake.run(), intake));


I think we should use subsystem factories in our examples whenever possible

Suggested change

controller.a().onTrue(Commands.runOnce(() -> intake.extend()));

controller.b().whileTrue(new RunCommand(() -> intake.run(), intake));

controller.a().onTrue(intake.runOnce(() -> intake.extend()));

controller.b().whileTrue(intake.run(() -> intake.run()));

agreed done

SamCarlberg · 2025-10-03T13:04:20Z

source/docs/software/commandbased/commands-v3/migration-from-v2.rst

+   );
+
+   new Trigger(() -> sensor.isTriggered())
+     .onTrue(Command.print("Sensor triggered!"));


That reminds me, we don't currently have a print command in v3

Is that just an oversight and there will / should be something like this in the future?

SamCarlberg · 2025-10-03T13:05:01Z

source/docs/software/commandbased/commands-v3/migration-from-v2.rst

+   CommandXboxController controller = new CommandXboxController(0);
+
+   controller.a().onTrue(
+     intake.run(coro -> intake.extend()).named("Extend Intake")


This could be _ -> intake.extend() if we're on Java 22 or higher

Is that style we want to adopt?

SamCarlberg · 2025-10-03T14:30:27Z

source/docs/software/commandbased/commands-v3/coroutines-and-async.rst

+
+### Wait and Delay Methods
+
+#### ``wait(Measure<Time>)``


Suggested change

#### ``wait(Measure<Time>)``

#### ``wait(Time)``

SamCarlberg · 2025-10-03T14:31:14Z

source/docs/software/commandbased/commands-v3/coroutines-and-async.rst

+
+#### ``fork(Command)``
+
+Starts a command in the background without waiting for it to finish. Returns a ``CoroutineFuture`` you can ``await()`` later.


LLM hallucination? fork returns void

SamCarlberg · 2025-10-03T14:32:25Z

source/docs/software/commandbased/commands-v3/coroutines-and-async.rst

+     intake.setSpeed(0);
+   }).named("Collect Until Full");
+
+### Parallel Actions with Timeout


I think we'd just use the withTimeout decorator instead of manually racing with timed wait commands

SamCarlberg · 2025-10-03T14:35:01Z

source/docs/software/commandbased/commands-v3/coroutines-and-async.rst

+
+### 4. Child Commands and Lifetimes
+
+Commands started with ``await()`` or ``fork()`` are "child commands" of the parent. If the parent is canceled, all children are automatically canceled.


likewise, interrupting a child command will also interrupt its parent (and its parent and... all the way up the chain). One child interrupting another, though, will not interrupt their shared parent

SamCarlberg · 2025-10-03T14:35:17Z

source/docs/software/commandbased/commands-v3/coroutines-and-async.rst

+     }
+   });
+
+### 2. Don't Yield Inside Synchronized Blocks


Not relevant if we're on Java 25

jasondaming · 2025-10-04T16:19:15Z

I think I touched them all. I will go back through the comments later to make sure

source/docs/software/commandbased/commands-v3/getting-started.rst

sciencewhiz

I'm really concerned about the amount of code, LLM hallucinations, and the fact that the framework hasn't had team feedback yet, so I expect more changes are coming. I think the code needs to be from examples or snippets, so we don't end up with code that doesn't work and isn't noticed.

sciencewhiz · 2025-10-27T00:14:36Z

source/docs/software/commandbased/commands-v3/index.rst

+
+Commands v3 is the next-generation command-based framework for Java that introduces imperative-style command writing using coroutines. Instead of building complex chains of lambda expressions and decorators, you can write command logic as straightforward sequential code with loops, conditionals, and explicit control flow.
+
+**WPILib recommends Commands v3 for Java teams.** Commands v3 is actively being developed with new features including improved telemetry, enhanced trigger functionality, and self-canceling commands.


I think it's too early to explicitly recommend Commands v3. I'd either be silent (and let teams make the decision based on the pros/cons below), or ask teams to try it and provide feedback.

There was discussion on this already and this was the way I was told to do it. I agree with you that the lack of testing at this point it concerning and it worries me too. By the time all this goes live in 2027 I hope I will feel much more comfortable.

sciencewhiz · 2025-10-27T00:16:06Z

source/docs/software/commandbased/commands-v3/index.rst

+**WPILib recommends Commands v3 for Java teams.** Commands v3 is actively being developed with new features including improved telemetry, enhanced trigger functionality, and self-canceling commands.
+
+.. warning::
+   Commands v3 is **Java-only** and does not support C++ or Python.


Somewhere it might be good to document why it's java only, but probably not here.

sciencewhiz · 2025-10-27T00:16:47Z

source/docs/software/commandbased/commands-v3/index.rst

+
+See :ref:`docs/software/commandbased/commands-v2/index:Commands v2 Programming` for the v2 documentation.
+
+## What's New in v3?


I'd put this ahead of the v3 vs v2 comparison

sciencewhiz · 2025-10-27T00:21:50Z

source/docs/software/commandbased/commands-v3/what-is-command-based-v3.rst

+
+## Mechanisms and Commands
+
+.. image:: ../diagrams/subsystems-and-commands.drawio.svg


This should be updated to replace subsystems with mechanism.

sciencewhiz · 2025-10-27T00:26:13Z

source/docs/software/commandbased/commands-v3/what-is-command-based-v3.rst

+
+See :ref:`docs/software/commandbased/commands-v3/command-compositions-v3:Command Compositions` for more details.
+
+## When to Use v3 vs v2


This also shows up in the index. Should only be one place

sciencewhiz · 2025-10-27T02:14:32Z

source/docs/software/commandbased/commands-v3/structuring-v3-project.rst

+
+## Example: Complete Small Project
+
+See the full example structure:


This is confusing. Is it missing a full project or link to full project? or is it duplicative of the first section?

sciencewhiz · 2025-10-27T02:16:20Z

source/docs/software/commandbased/commands-v3/migration-from-v2.rst

+
+## Should You Migrate?
+
+**WPILib recommends migrating to Commands v3 for Java teams.** Commands v3 is the future direction of command-based programming with ongoing development and new features including improved telemetry, enhanced triggers, and self-canceling commands.


Similar to my previous comment, I think this needs to be reworked to not be so final on a framework that doesn't have much runtime

sciencewhiz · 2025-10-27T02:17:07Z

source/docs/software/commandbased/commands-v3/migration-from-v2.rst

+**Migrate to v3 if:**
+
+- You're a Java team
+- You want to use the actively developed command framework


Given the number of PRs for v2, I think both v2 and v3 are actively developed

sciencewhiz · 2025-10-27T02:18:17Z

source/docs/software/commandbased/commands-v3/migration-from-v2.rst

+
+### 1. Always Yield in Loops
+
+In v3, **you must call** ``coroutine.yield()`` inside any loop. If you don't, the scheduler can't run other commands, and your robot will freeze.


It has happened

sciencewhiz · 2025-10-27T02:21:58Z

source/docs/software/commandbased/commands-v3/coroutines-and-async.rst

+
+## Critical Rules and Gotchas
+
+### 1. Always Yield in Loops


add something about compile error

Move all Commands v2 documentation files into a commands-v2/ subdirectory to prepare for Commands v3 documentation. This is Phase 1 of the Commands v3 documentation project. Changes: - Move 12 v2 documentation files to commands-v2/ subdirectory (preserving git history) - Create new commands-v2/index.rst as landing page for v2 docs - Update main commandbased/index.rst to serve as high-level framework chooser - Update 24 files with corrected cross-references to new v2 locations - Add 12 redirects to ensure old URLs continue working This reorganization addresses feedback on PR wpilibsuite#3095 to split the work into manageable phases. The next phase will add v3 documentation structure with TODO placeholders. Related to wpilibsuite#3095

Move all Commands v2 documentation files into a commands-v2/ subdirectory to prepare for Commands v3 documentation. This is Phase 1 of the Commands v3 documentation project. Changes: - Move 12 v2 documentation files to commands-v2/ subdirectory (preserving git history) - Create new commands-v2/index.rst as landing page for v2 docs - Update main commandbased/index.rst to serve as high-level framework chooser - Update 20 files with corrected cross-references to new v2 locations - Add 12 redirects to ensure old URLs continue working This reorganization addresses feedback on PR wpilibsuite#3095 to split the work into manageable phases. The next phase will add v3 documentation structure with TODO placeholders. Related to wpilibsuite#3095

Create skeleton structure for Commands v3 documentation with section headers and TODO notes describing what content should go in each section. This phase establishes the documentation organization for review before content is written. Files created: - index.rst: Landing page with overview and quick examples - what-is-commands-v3.rst: Conceptual foundation and core concepts - getting-started.rst: Hands-on tutorial for first v3 program - mechanisms.rst: Deep dive into Mechanisms (v3's Subsystems) - commands-and-coroutines.rst: Core command creation and coroutine API - async-await-patterns.rst: Async/await helpers for orchestration - command-compositions.rst: Traditional composition groups - binding-commands-to-triggers.rst: Button bindings and triggers - priorities-and-interrupts.rst: Priority system and interruption - structuring-v3-project.rst: Code organization best practices - testing-and-simulation.rst: Testing commands with simulation - telemetry-and-debugging.rst: Enhanced telemetry and debugging - migration-from-v2.rst: Migration guide from v2 to v3 - advanced-topics.rst: Advanced patterns and edge cases Each file contains: - Section headers outlining the article structure - TODO directives describing what content should be written - Guidance for future content writers on what to include No actual tutorial content or code examples are included - this is purely structural planning for review. Related to wpilibsuite#3095 Related to wpilibsuite#3165

Move all Commands v2 documentation files into a commands-v2/ subdirectory to prepare for Commands v3 documentation. This is Phase 1 of the Commands v3 documentation project. Changes: - Move 12 v2 documentation files to commands-v2/ subdirectory (preserving git history) - Create new commands-v2/index.rst as landing page for v2 docs - Update main commandbased/index.rst to serve as high-level framework chooser - Update 20 files with corrected cross-references to new v2 locations - Add 12 redirects to ensure old URLs continue working This reorganization addresses feedback on PR wpilibsuite#3095 to split the work into manageable phases. The next phase will add v3 documentation structure with TODO placeholders. Related to wpilibsuite#3095

Create skeleton structure for Commands v3 documentation with section headers and TODO notes describing what content should go in each section. This phase establishes the documentation organization for review before content is written. Files created: - index.rst: Landing page with overview and quick examples - what-is-commands-v3.rst: Conceptual foundation and core concepts - getting-started.rst: Hands-on tutorial for first v3 program - mechanisms.rst: Deep dive into Mechanisms (v3's Subsystems) - commands-and-coroutines.rst: Core command creation and coroutine API - async-await-patterns.rst: Async/await helpers for orchestration - command-compositions.rst: Traditional composition groups - binding-commands-to-triggers.rst: Button bindings and triggers - priorities-and-interrupts.rst: Priority system and interruption - structuring-v3-project.rst: Code organization best practices - testing-and-simulation.rst: Testing commands with simulation - telemetry-and-debugging.rst: Enhanced telemetry and debugging - migration-from-v2.rst: Migration guide from v2 to v3 - advanced-topics.rst: Advanced patterns and edge cases Each file contains: - Section headers outlining the article structure - TODO directives describing what content should be written - Guidance for future content writers on what to include No actual tutorial content or code examples are included - this is purely structural planning for review. Related to wpilibsuite#3095 Related to wpilibsuite#3165

Move all Commands v2 documentation files into a commands-v2/ subdirectory to prepare for Commands v3 documentation. This is Phase 1 of the Commands v3 documentation project. Changes: - Move 12 v2 documentation files to commands-v2/ subdirectory (preserving git history) - Create new commands-v2/index.rst as landing page for v2 docs - Update main commandbased/index.rst to serve as high-level framework chooser - Update 20 files with corrected cross-references to new v2 locations - Add 12 redirects to ensure old URLs continue working This reorganization addresses feedback on PR wpilibsuite#3095 to split the work into manageable phases. The next phase will add v3 documentation structure with TODO placeholders. Related to wpilibsuite#3095

Create skeleton structure for Commands v3 documentation with section headers and TODO notes describing what content should go in each section. This phase establishes the documentation organization for review before content is written. Files created: - index.rst: Landing page with overview and quick examples - what-is-commands-v3.rst: Conceptual foundation and core concepts - getting-started.rst: Hands-on tutorial for first v3 program - mechanisms.rst: Deep dive into Mechanisms (v3's Subsystems) - commands-and-coroutines.rst: Core command creation and coroutine API - async-await-patterns.rst: Async/await helpers for orchestration - command-compositions.rst: Traditional composition groups - binding-commands-to-triggers.rst: Button bindings and triggers - priorities-and-interrupts.rst: Priority system and interruption - structuring-v3-project.rst: Code organization best practices - testing-and-simulation.rst: Testing commands with simulation - telemetry-and-debugging.rst: Enhanced telemetry and debugging - migration-from-v2.rst: Migration guide from v2 to v3 - advanced-topics.rst: Advanced patterns and edge cases Each file contains: - Section headers outlining the article structure - TODO directives describing what content should be written - Guidance for future content writers on what to include No actual tutorial content or code examples are included - this is purely structural planning for review. Related to wpilibsuite#3095 Related to wpilibsuite#3165

Move all Commands v2 documentation files into a commands-v2/ subdirectory to prepare for Commands v3 documentation. This is Phase 1 of the Commands v3 documentation project. Changes: - Move 12 v2 documentation files to commands-v2/ subdirectory (preserving git history) - Create new commands-v2/index.rst as landing page for v2 docs - Update main commandbased/index.rst to serve as high-level framework chooser - Update 20 files with corrected cross-references to new v2 locations - Add 12 redirects to ensure old URLs continue working This reorganization addresses feedback on PR #3095 to split the work into manageable phases. The next phase will add v3 documentation structure with TODO placeholders. Related to #3095

jasondaming added 2 commits September 30, 2025 07:59

first shot needs refining

dd05c58

reorganized the command structure splitting them in 2

1e43f44

github-actions bot added the 2027 label Oct 3, 2025

canceling spelling and pdf build issues

4e6580c

SamCarlberg reviewed Oct 3, 2025

View reviewed changes

source/docs/software/commandbased/commands-v3/command-compositions-v3.rst Show resolved Hide resolved

Fixed example and errors

de8ae2e

SamCarlberg reviewed Oct 3, 2025

View reviewed changes

Addressing Sam's comments

013400c

jasondaming added 2 commits October 4, 2025 12:24

fix duplicate label

d3ad0b2

More changes based on comments

9cd20a1

katzuv reviewed Oct 6, 2025

View reviewed changes

addressing comments #1 needed drivetrain.run

c411163

This was referenced Oct 10, 2025

Improve documentation on transitioning from Command classes to inline factory methods #3016

Open

Add C++ docs to organizing command based page #2724

Open

sciencewhiz reviewed Oct 27, 2025

View reviewed changes

jasondaming mentioned this pull request Nov 13, 2025

Reorganize command-based documentation for v2/v3 separation (Phase 1) #3164

Closed

7 tasks

jasondaming mentioned this pull request Nov 13, 2025

Reorganize command-based documentation for v2/v3 separation (Phase 1) #3165

Merged

7 tasks

jasondaming mentioned this pull request Nov 13, 2025

Add Commands v3 documentation outline (Phase 2) #3166

Open

10 tasks

		controller.a().onTrue(Commands.runOnce(() -> intake.extend()));
		controller.b().whileTrue(new RunCommand(() -> intake.run(), intake));


		#### ``fork(Command)``

		Starts a command in the background without waiting for it to finish. Returns a ``CoroutineFuture`` you can ``await()`` later.


		### 4. Child Commands and Lifetimes

		Commands started with ``await()`` or ``fork()`` are "child commands" of the parent. If the parent is canceled, all children are automatically canceled.


		Commands v3 is the next-generation command-based framework for Java that introduces imperative-style command writing using coroutines. Instead of building complex chains of lambda expressions and decorators, you can write command logic as straightforward sequential code with loops, conditionals, and explicit control flow.

		WPILib recommends Commands v3 for Java teams. Commands v3 is actively being developed with new features including improved telemetry, enhanced trigger functionality, and self-canceling commands.


		See :ref:`docs/software/commandbased/commands-v2/index:Commands v2 Programming` for the v2 documentation.

		## What's New in v3?


		## Mechanisms and Commands

		.. image:: ../diagrams/subsystems-and-commands.drawio.svg


		See :ref:`docs/software/commandbased/commands-v3/command-compositions-v3:Command Compositions` for more details.

		## When to Use v3 vs v2


		## Example: Complete Small Project

		See the full example structure:


		## Should You Migrate?

		WPILib recommends migrating to Commands v3 for Java teams. Commands v3 is the future direction of command-based programming with ongoing development and new features including improved telemetry, enhanced triggers, and self-canceling commands.


		### 1. Always Yield in Loops

		In v3, you must call ``coroutine.yield()`` inside any loop. If you don't, the scheduler can't run other commands, and your robot will freeze.

Commands v3 Documentation #3095

Are you sure you want to change the base?

Commands v3 Documentation #3095

Uh oh!

Conversation

jasondaming commented Oct 3, 2025

Uh oh!

Uh oh!

SamCarlberg left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jasondaming commented Oct 4, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sciencewhiz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

SamCarlberg left a comment •

edited

Loading