I'm picking up renaming `fmt` to `fix`. Speak now or forever hold your peace

It's just going to be annoying telling my team whos just getting used to

fmt

to use fix.

tbh.. feels like busy work… I don't see the actual user benefit. I didn't (and won't ) bother reading the ticket (there is so much comments on it…) feels like a total waste of brain cycles 🤷‍♂️ There is so much other stuff that could be done to improve usability and perf.. that I don't see the point of doing this kind of work or even considering it.

@ambitious-actor-36781 I can sympathize for sure. My own dayjob's users will likely have a few bricks to lob my direction. Rest assured we'll be following our deprecation policy (and possibly extending the normal cycle), where your code and commands are still valid after an upgrade (save for some warnings or forced settings). So even after upgrading you can still use

fmt

for at least a version (if not more, this is a large change). I also want to highlight that this policy exists so Pants can evolve over time. As we decide we want to do more interesting and creative things, or find the err in our past ways we have two options: • Bend: in this case that means making these breaking changes slowly and methodically with some heartburn along the way • Break: Slap a new version (Pants v3) or a new name because we broke too much I'm glad we're dedicated to bending so that, over time, we can continue to grow internally and with the community.

I was concerned that this would be a pain point for teams which recently onboarded to Pants (like mine), since they'd have to change the command they enter most often. But if we have

fix --style-only

then we can keep

fmt

around as an alias for low (no?) cost. I think if we keep it around for long enough (maybe even until 3.0), this won't be a problem.

So part of the motivation as well is to avoid a proliferation of goals. So eventually

fmt

will be removed. However you'll love the fact that you can define your own CLI aliases: https://www.pantsbuild.org/docs/reference-cli So

fmt

could always live on in your repo or on your machine as an alias ☺️ (FYI @ambitious-actor-36781. I forgot to mention this as well)

Having been pretty involved in commenting on this one - did any "final" proposal actually land? I feel like Eric's gdoc and the Github issue all had a lot of well thought-out pros/cons, but it wasn't as simple as a re-naming, it was basically revisiting the entire `check`/`lint`/`fmt`/`tailor`/`update-build-files` API to see what should be merged, what needed options, what should be re-named. For example, at the end of the proposal, it says something with an "if", giving it a sense of not being a final decision:

If we do want to add non-safe "fixers", we should consider using a dedicated goal like tailor or something new.

@bitter-ability-32190 Could you maybe enumerate what changes that ticket would cover, so we have an idea of the scope of API change? Anything that reduces the number of goals and improves goal semantics gets a big 👍 from me. Conversely, anything that changes the external API but leads to basically "the same thing" gets a huge 👎 ... Hence averaging out to strongly neutral...

I need to regenerate some API spec files, but the files have to be checked in because people consume them via GitHub raw content. Codegen seems like it would be perfect, but nothing in the repo depends on those files. I ended up adding a

fmt

plugin for it to ensure it happens regularly. But I cringe because this is very much not formatting.

fix

would not cause the cringe. So a big 👍 from me.

In the end I believe update-build-files will be folded into

fix

, but we need to have

fix

for that to be allowable. Additionally I would expect the formatting aspect v the fixing aspect to be split.

tailor

I believe was determined to be special enough to remain. I don't think we discussed non-safe fixers, however I wouldn't want us to make design decisions based on "maybe" future state (after all, as said above we have ways of changing over time) So this is the first step to a few of those possible additional tasks, which is why I'm picking it up.

I understand the reasoning here, but churn on public APIs has a strong impact. As someone who's fighting an uphill battle to even get adoption in his org, this kinda design churn hurts. It makes arguing cases for Pants much harder, because this is the kinda stuff that our users are expected to use.

@flat-zoo-31952 what about setting up a

[cli].alias

so that

fmt

==

fix

in your repo, meaning people don't have to change if you don't want them to?

It's one thing to churn in the more internal parts of Pants: plugin API, more sophisticated options, even target field names—because these things are mostly irrelevant to a typical developer's workflow, and can be managed by a team of specialists who follows Pants changes more closely. But goals are the most visible part of the Pants public API that would be used by a broad subset of users. And changing this stuff too often sends a subtle message that this is beta software. I'm of the opinion that if a goal is added, it should be kept for quite a bit longer than the current deprecation policy suggests. Perhaps deprecated goals should remain available as pluggable backends for several version cycles? It's some maintenance and some extra tests, but I think that's part of the cost of building software that people actually use

Actually the options will be the same, plus a new one. All of the options on

fmt

are valid for

fix

. So unless you're using the subsystem name (e.g.

--fmt-only=...

) You shouldn't see the difference

That could be an option. And then I like that both

fmt

and

fix

can show up in

./pants help goals

, and we can explain

fmt

is a (deprecated) subset of the

fix

goal, which does not include semantic "fixers" like PyUpgrade and Scalafix

Re churn: if we determined that the proposal is the direction we want to go, it'll hurt less at 100 adopters than 1000.

That's fine, but that is very much a beta software approach. And at some level I can't argue with it because I get the need to move forward, and I get that design is an iterative process. And it works within your depreciation policy. But I can say as a user it's frustrating. I don't think about Pants every day. I can't afford to. I don't think I'm alone in that. So when I come back and I see that goals are moving again, it takes mental energy to figure out what's going on, even if there are workarounds available. This change sounds okay I guess, and it does show that you think about your users in this. But decisions like this clearly get made by people who get to think about Pants all the time. So it still feels like you're missing a "person who uses Pants but has other duties" UX persona from your design process. So I don't have a great logical argument here. I just have the observation that churn is deeply frustrating as a user, especially for things that for all intents and purposes felt fine.

Goals are moving again

Can you elaborate? I'm getting the impression there's a past experience that bit you as well, and I'd love to know what it was. And can you help me understand what would make this change easier to digest if you were reading the release announcement or however you consume an upgrade?

I'm feeling a lot of intensity behind the rename

The consequence of touching a public API, unfortunately - broad-reaching implications, with potentially minimal benefits for most/all of the user base

concrete ideas on how to manage the pain

I think as mentioned in either the GH issue, or GDoc, or maybe even this thread - if there is/are built-in aliases, or automation ways to solve this - those are decent pain mitigation strategies. When there are BUILD file target name changes (which is also a public API change), we have a dedicated command that fixes them and it's approximately zero mental exertion other than reading a deprecation note after updating pants. No big deal. If

fmt

stops existing (or any goal, actually), then there is some amount of mental exertion, and there might be build scripts, CI tools, etc that all need to be updated in any repo using Pants. I have a bunch of Pants repos, and that's not a big deal for me - but for some people, that's much harder due to larger scripting facilities, or just wayyyyyy more people involved in the process. My assumption/hope would be that on any public API change, there is a "lengthy" deprecation time, automated script updates, and documentation notes the deprecated version but auto-redirects to the newer version.

@bitter-ability-32190 I wonder if we could keep

fmt

in like a "hidden" state for a long long time, even after a long normal deprecation. Like, it doesn't show up in

./pants help goals

, but if you type it, we treat it as

fix --style-only

, and print a short deprecation saying to use

fix

instead. Seems very technically feasible

a short deprecation

To reduce CLI noise. And Pants users can use the

ignore_warnings

option if they really don't want that warning

I only sorta get that "API churn means beta software" feeling, but like - that might be a language or industry thing too. Any web developer knows how severe API churn can get, while I have C libraries from 15 years ago I can still plug and play. So long as the API change leads to a tangible improvement (knowing that "improvement" is subjective), I think they're fair game, even in build tools. BUT! I will say that when it comes to API changes, I, personally, would like to suffer pain all at once, rather than every few releases, seeing a goal change or break.

with potentially minimal benefits for most/all of the user base

For clarity: the intended benefit of this change is so that we can move forward adding semantic fixers to what is now the

fmt

goal, including merging

update-build-files

. Technically, we could have

./pants fmt

do things like BUILD file deprecation fixers...but that semantically is wrong

"hidden" state for a long long time, even after a long normal deprecation

I'm struggling to remember the tool or language I saw this in, but one pattern I've seen is that public API changes are never officially breaking until a major version change. I know that just sounds like semantic versioning, but it was pretty awesome. The deprecated API was basically invisible unless you had already used it in the past. So, new users wouldn't really even know it existed, while existing users were completely unaffected until a 3.0 release.

Can you elaborate? I'm getting the impression there's a past experience that bit you as well, and I'd love to know what it was.

I think I just value API stability a lot. It's come up before, although I can't recall the specifics now, and the Slack history is probably gone. IIRC I think it was some changes that were made in prep for target generators, which ended up being a really good idea, but it was frustrating to deal with then. There's a lot of smart people working on this project, and often things are being done to make way for some really cool ideas in the future, but the benefit to users in the meantime is often very unclear in the short term. This is normal with any kind of upgrade process.

It's come up before

python_library -> python_sources

, iirc. It was SUPER disruptive, even though it was automated

It was SUPER disruptive

Not only BUILD file churn, but you had to update things like

./pants filter --target-type

to differentiate between

python_source

vs

python_sources

, in some cases

Technically, we could have

./pants fmt

do things like BUILD file deprecation fixers...but that semantically is wrong

@hundreds-father-404 Exactly. The semantics would matter to someone like me... but, to 90% of the userbase? Who knows if they're as pedantic as me 🙂

I think I feel strongly against

fmt

running "semantics-changing fixers" because a major design goal for Pants is to be _intuitive_: you can figure it out without reading docs prior knowledge. Which is key because we try to assume most of our non-Slack users barely read our docs

Yeah, but I don't see a problem with goal proliferation, especially if you can find a way to make some of the less desirable goals "hidden" somehow

yeah, I am fine with keeping

fmt

around ~indefinitely, as long as new users only encounter

fix

. it's not much code for us to support that

But I could be wrong, and I know that doing this universally causes confusion and non-trivial maintenance burden

Is that not a product of learning from our mistakes? Eventually the pendulum stops swinging because we found the right steady-state

@flat-zoo-31952 @ambitious-actor-36781 @wide-midnight-78598 Thank you so much for bringing up this perspective. You're absolutely right that the majority of the maintainers team aren't in your position as a Pants admin supporting a lot of new and potentially resistant end-users, and underrepresentation of that perspective is a known weakness (which we've been actively working to remedy by recruiting more people like y'all, including @bitter-ability-32190, onto the maintainers team). Please do continue to advocate here for your end-users and keep helping us understand their usage and concerns as well as your own as a Pants admin. Feedback like yours is so valuable and necessary. I hope we ultimately get to have each of you on the maintainers team. And please do reach out to me anytime if you'd be interested in pursuing that as a goal!

But we've gotta be pushing towards a point at which some of this becomes more stable. Right?

My two cents is that certain parts of the system should be stable stable, whereas others we will want to have time to discover the best representation. Specifically: experimental backends. Whereas ideally we stop changing fundamental things like CLI specs, the core goals, targets in general

@flat-zoo-31952 @ambitious-actor-36781 @polite-garden-50641 @wide-midnight-78598 What's y'all's feelings on just adding a

fix

goal separate from

fmt

? We'd still dissolve

update-build-files

into both goals. But we've introduced another goal. I would say some of the pain of a new goal like this might be alleviated with fixing https://github.com/pantsbuild/pants/issues/10542. Then we can revisit the merging separate from the above

I read @fast-nail-55400’s latest issue comment, and I think it was an excellent synopsis of the practical issues with changing the public API. As I stated early in the Github thread, I dislike API-creep, and I'm a bigger fan of

./pants lint --fix

in lieu of a dedicated

fix

command, but that might just speak to what my day-to-day languages/tools are (not Rust with

cargo fix

and not Go with

go fix

). I'm not sure I understand what the technical scope of

fix

would be (as in, what identifies that which is `fix`able? Moreover, would we have the idea of a

fix --check-only

for CI? that just seems strange) If

fmt

was relegated to whitespace, unused imports/vars, braces, indents, and strictly visual presentation - I'm a huge +1 on that (no semantic or code-flow changes, and nothing that would change compiled byte-code). I think

fmt

is currently like 95% this, other than like 1 or 2 plugins. Would

update-build-files

have its duties split into two?

fmt

handles the visual presentation, while

fix

would handle any semantic tweaks (ie. target name changed)? I think this is the most practical, community-centric approach. Nothing severe breaks, additive API, and then deprecating and removing an API which becomes redundant.

Yup you got the gist. Lint would also run fixers to check code, just as formatters. So your CI still only needs lint and check.

Adding makes more sense to me in this case. I didn't fully get why these needed to be grouped together in the first place.

Go - "Fix finds Go programs that use old APIs and rewrites them to use newer ones. After you update to a new Go release, fix helps make the necessary changes to your programs." Rust - "cargo-fix - Automatically fix lint warnings reported by rustc" Which one is closer to what we would do?

After going over this again, i'd argue that

fix

is too general a term for these actions, at least as a goal. And it would be confusing to have it present along with

lint --fix

if that was adopted as well

I think I would expect

./pants update

to update itself

It's kinda what's nice about a term like

tailor

, even if it comes from a silly pun, is that it has no overloaded expectations of behavior

If other ecosystems already have the notion of fix, why wouldn't we borrow that schema?

Because their notions are different

It doesn't have to be perfect, just good enough. Also I think brevity is important here, as we want it to fit in with fmt and lint

Idk about "good enough", and when creating a new API it's good to be careful. Otherwise you have a tendency to back yourself into corners it's hard to get out of once people start binding themselves to the workflows you've allowed them to create

Seems like at this point we're not discussing if there should be a new goal, but what it should be named. I'll make a new thread so we can discuss without this threads history.

just caught up: thank you everyone for the thoughts in this thread, and to @bitter-ability-32190 for your patience. my takeaways are: 1. we should probably consider committing to a longer deprecation cycle for “the most visible” user APIs like goals. or at the very least start a convention about choosing appropriate deprecation periods for changes, rather than always going for the minimum period. 2. the pivot to a discussion on naming over here is great. if discussion starts to slow down, consider writing the choices up as a contentious decision vote (not necessarily because it’s contentious, per-se, but mostly to ensure that the choices are clearly enumerated, and everyone interested gets heard)

Did you have an opinion on new goal name for the other thread?

not yet, but if you’re trying to decide today i can take a look

No, today is mostly for resting 🤒

will try to before tomorrow.

My actual end goal is to dissolve that goal so I don't have to run it, and to allow for in-repo build file formatters, dissolving a chunk of my in-repo plugins 😅 One PR I can make today is a "<none>" formatter option for build files (required if I'm gonna plug my own)