https://pantsbuild.org/ logo
#development
Title
# development
f

flat-zoo-31952

10/14/2022, 5:54 PM
🔪 🥫 🪱 Okay... I've made a good bit of progress on a proposal for a new deprecation policy. The big change of this policy from the existing one is that it recommends never deprecating public APIs (with a few exceptions). I've included some analysis of different personae that are using Pants, and it's just really hard to make any kind of meaningful user-centric justification for the current deprecation policy. And while I've tried to avoid diving into implementation recommendations in this document, it really seems to me that this could be fairly easily maintained with an alias/translation layer feature that could translate between old options/defaults and new ones. This is still a work in progress, but I'd love some feedback on this. More in 🧵
❤️ 1
🫤 1
I've included the following as exceptions to the policy: • Changes required by law or legal decisions • Fixes for major security vulnerabilities • Features whose maintenance induces an excessive burden on the Pants Team • Actively harmful misfeatures • Anything in preview/experimental state Some items there give some judgement back to the team to decide that keeping an API feature may be harmful, but the overall thrust of the document is to push us in a direction of strong API stability
❤️ 1
This will also be a topic on monday in the next Pants team meeting, so I'll be glad to discuss this via video chat. I'd prefer that anyways, so I can use my loud voice, strong beard, and charismatic presence to influence you all to agree with me 😈
😈 2
Also note that I consider the efforts to have good, evolving, sensible defaults for new users to be very worthwhile, so this isn't about freezing things in stone. It's about recognizing the toll that churn has on your users, and trying to imagine a way forward that can meet both goals, although most likely at the expense of interface bloat. To handle interface bloat, the policy recommends using the "advanced" flag or a new "deprecated" flag to hide legacy interfaces from default help and documentation views.
👆 1
w

wide-midnight-78598

10/14/2022, 6:15 PM
Thanks for doing all this, it's a great read so far. I largely agree with this, with one gigantic exception - which is that a major version change should allow breaking changes. The technical debt creep and death by a thousand aliases isn't a problem in the short term, but definitely adds up. Maintenance burden, naturally - but also the cost of onboarding of new contributors/maintainers to an open-source project. I'd be very nervous codifying a policy that doesn't allow for a clean break via versions, especially as it's up to the users to perform the update. I guess I'm also not a fan of taking a harder API line than a lot of the languages, SDKs, frameworks, and tools we support.
A secondary concern about this harder line would be the desire to keep more stuff in `preview`/`experimental` - which has its own set of concerns The most obvious and egregious example of this would be Black, where the concern of "stability" was pretty extreme I think. https://github.com/psf/black/blob/main/CHANGES.md#2210 Leading to this fun 130ish comment issue: https://github.com/psf/black/issues/517
f

flat-zoo-31952

10/14/2022, 6:25 PM
I expect and welcome the "death by 1000 cuts" argument, and that might be the best reason we have for wanting to sunset some features eventually. But I don't know if "major version" changes is the way to do it, since it's just such a good way to fork the community. So i'd be open to perhaps some allowance for longer-term deprecations, but the "this is the version where we break things" feels much worse. I'm more in the bend-don't-break camp, i just believe in bending for a really really really long time 😄
w

wide-midnight-78598

10/14/2022, 6:30 PM
Sure, I'm using the major version as just one, commonly accepted "clean API slate" option. We've been on 2.x for a couple of years, so it's not something that changes often, nor would I expect a future major version change to be similar to the 1.x to 2.x one. Also, as the plugin API policy isn't written, as that's developer-centric - not human-centric (like the CLI), I would propose a looser deprecation policy there for certain. With the emphasis of automated migrations as much as possible.
f

flat-zoo-31952

10/14/2022, 6:31 PM
I'm open to other exceptions as well, I just want them to be well-defined (this is a weakness of the current document) and, well, exceptional.
👍 1
I think there's been far too much churn in an effort to get things "right", and while I agree that's resulted in a sleeker and more consistent interface, it's really hard to deal with the changes in an actual installation, especially as someone who thinks about Pants maybe 5-10% of the time while working. Knowing I could upgrade (or even sometimes downgrade) Pants and mostly not think about it would be a huge win.
I think of
git
a lot... it's interface kinda sucks sometimes and is inconsistent from command to command, but I never really worry about it not working, unless I stumble onto some ancient version
w

wide-midnight-78598

10/14/2022, 6:58 PM
That's a fair point, but as a counter-point - what if
git
was only a couple years old in its current incarnation, with a user base that was 100-1000x smaller? I think it would be in a situation where consistency and cleanliness can have a higher priority over ultimate stability It's a wobbly see-saw type of problem. I look at Bazel as a decent case study, where I think the API is pretty stable nowadays, but half the time, it's incomprehensible to me. 🤷
However, for the plugin API - if I could run:
./pants migrate ::
Well, that's a lot of grief solved. The CLI is trickier though, admittedly. I say all of this as someone who uses pants in about 25 repos with 10 clients so far - so anything breaking will require some pain and suffering, but I've also gone through LOTS of major breaking upgrades of languages and frameworks. More often than not, the fear of it is worse than the action - and, other than XCode/Swift, I've chosen if/when I'm upgrading. This also puts me on the side of the discussion which accepts breaking changes as a fact of life with open source software, so long as it's on my terms.
b

bitter-ability-32190

10/14/2022, 8:02 PM
I'll save opinion for the discussion. One thing I don't see listed is if changing output is a breaking change. Or read another way, what guarantee do we have about our stdout of goals and rules?
🤔 1
b

busy-vase-39202

10/14/2022, 8:02 PM
I like the idea of an exception for major version changes, and that could be tailored. For instance, a major version change gives permission to introduce breaking changes, but doesn't impose obligation to. It's not a trash chute.
b

bitter-ability-32190

10/14/2022, 8:14 PM
One issue of the major version lens if we really think there'll ever be a v3
h

happy-kitchen-89482

10/14/2022, 8:44 PM
Thanks @flat-zoo-31952! Looking forward to the discussion on Monday
👍🏻 1
w

witty-crayon-22786

10/14/2022, 9:18 PM
thanks a lot: added comments over there.
b

bitter-ability-32190

10/14/2022, 10:37 PM
Hm I think another point of contention would be changing defaults
f

flat-zoo-31952

10/15/2022, 12:14 AM
Why changing defaults? That’s in the existing deprecation policy btw
b

bitter-ability-32190

10/15/2022, 12:16 AM
Ah okie doke
By "point of contention" I meant "topic to add", my b
b

busy-vase-39202

10/15/2022, 1:05 AM
Thanks for doing this @flat-zoo-31952. You've put months of thought into drafting a policy that prioritizes end-user experience. Much needed and much appreciated. I'm looking forward to the discussion on Monday.