Fix confusing error for an @console_rule not returning a Goal
#8931
Conversation
Eric-Arellano
force-pushed
the
console-rule-error
branch
from
1086dd1
to
ae46190
Compare
|
I'm not sure if we actually want to enforce that |
Should they? I don't think so, personally. My mental model for Instead, I think your mental model might be closer to "a rule that should not be cached"? That detail comes more from the implementation. If we wanted console rules to be able to call console rules, then I think |
Exactly. And I'm not personally sure whether the important thing about cf. the discussion on #8922 |
I think it will always make sense to have Instead, we would add a new rule type called -- Whether we add |
|
@gshuflin - Currently if you write an @console_rule that doesn't return a Goal the engine throws an error stating that "@rules that return Goals must be @console_rules" which is supremely unhelpful. So whether we should accept @console_rules that return things other than goals or not seems to be a different question. This PR is just improving the confusing error message and not actually changing the behavior of pants. |
|
Ok, @TansyArron @Eric-Arellano I think I agree that this commit is okay as-is and the discussion about how to handle rule cacheability correctly is something that should be punted on. |
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 #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](https://www.pantsbuild.org/first_concepts.html) 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.
Closes #8930.