Rename @console_rule to @goal_rule

[Eric-Arellano]

Any time that you add a new top-level goal in V2—that is a "verb" for Pants like test, fmt, setup-py, and dependencies—you must define the same three basic things:

Goal, GoalSubsystem, @console_rule

One of those does not fit with the other two. In contrast, these three all belong:

Goal, GoalSubsystem, @goal_rule

What is an @console_rule?

There are (at least) 3 ways of conceptualizing what an @console_rule means:

1. A rule that has exclusive access to the Console.
   • Only @console_rules can write to stdout and stderr.
   • This property is represented in the name @console_rule.
2. A rule that is not cached.
   • This is an important property of @console_rules and contrasts with normal @rules.
   • Per the conversation in Fix confusing error for an @console_rule not returning a Goal #8931 (comment), this idea on uncachability is the main mental model for some.
3. A rule that maps 1-1 with a top-level goal / returns an engine.goal.Goal.

All three of these properties are true and important components of an @console_rule. However, I argue that #3 is the most important: fundamentally, an @console_rule is a special rule that hooks up to a Pants goal.

Right now, the name @console_rule optimizes for property #1. In contrast, @goal_rule focuses on property #3.

(NB: all three of these properties will continue applying regardless of the name)

Leveraging prior Pants knowledge

Most Pants users are familiar with the idea of a goal. It's the very first concept introduced in our docs and every single Pants run involves invoking goals, regardless of V1 vs. V2.

In contrast, fewer users are familiar with the Console abstraction, which is never mentioned in our docs and is more of an implementation detail for how V2 Pants works.

We do expect users to soon write their own rules in plugins. The name @goal_rule will allow them to leverage their prior knowledge, just as subsystem_rule leverages prior knowledge better than optionable_rule did.

[pierrechevalier83]

A little bit of a heavy-handed change, so I would like to see many approvals before this got merged; but I agree with the reasoning and I think this change would help for teachability of the pants concepts to new contributors 😄

[herman5]

Good stuff, Eric! I’m onboard with @goal_rule for exactly what you outlined:

Goal, GoalSubsystem, @console_rule - One of those does not fit with the other three

Given that I’m still new to Pants V2, the @goal_rule convention fits easily into my mental model along with being easy to remember (@console_rule actually requiring effort to recall as the naming is more orthogonal).

[codealchemy]

👍 👍 (for the same reasons you and others have already touched on)

[cosmicexplorer]

This is a really well-thought-out argument. Thank you for taking the time to describe it so clearly!

[stuhood]

Works for me.

Not to throw a wrench in the works, but: did you consider just @goal...? I'd be fine with either

[gshuflin]

Works for me.

Not to throw a wrench in the works, but: did you consider just @goal...? I'd be fine with either

I'd vote for @goal_rule over @goal to make it clearer that a @goal_rule is still a type of @rule

[Eric-Arellano]

I'd vote for @goal_rule over @goal to make it clearer that a @goal_rule is still a type of @rule

Plus one. I also find the difference between Goal and @goal slightly confusing.

Thanks for the reviews, everyone! Will merge once this goes green.