🔪 🥫 🪱 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 🧵

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.

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 😄

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.

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.

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. 🤷

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?

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.

One issue of the major version lens if we really think there'll ever be a v3

Thanks @flat-zoo-31952! Looking forward to the discussion on Monday

thanks a lot: added comments over there.

Hm I think another point of contention would be changing defaults

Why changing defaults? That’s in the existing deprecation policy btw

Ah okie doke

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.