> We as spectators should applaude, not bike shed. Absolutely!
To be totally transparent, my immediate concern is for two of my own tickets (SOLR-17562 and SOLR-16825) where I'm trying to weigh the slight user-inconvenience of a package-move against the slight benefit. That got me curious about whether we had any consensus around deprecation, so I raised this thread. Any applicability to any of David's recent work is 100% unintentional on my part. David - feel free to ignore this thread entirely if it's at risk of slowing down any open PRs you have. > I love the idea of a dev-docs/deprecation.adoc I think I mentioned this above, but I'd love to open a PR for this. We just have to arrive at that consensus in order to document it... One area where it does seem like there's consensus is on the idea that all deprecations should be actionable. (In the rename context I guess that's a "shim"). Not sure that helps us with the question of when we think deprecation is merited, but it's a start. On the "when is deprecation merited" question, here's where it sounds like folks are: - Gus - no deprecation - "A simple in-place rename [...] doesn't seem like it needs deprecation to me." - Jan - deprecation is ideal, but "not a crisis" if missed on accident - " imo any breaking change that will make the user's code no longer compile (such as package change) needs a deprecation" - David - no deprecation - "I don't want us increasing our Solr maintenance burden further by adding deprecated annotations and shims for moving classes *on a major release*." - Jason - probably closer to Jan's "deprecation is ideal" perspective In other words: not much consensus. Is there any sort of middle-path wording that folks could get on board with? e.g. "Renaming should involve deprecation and a shim where it's convenient to do so, but is not strictly required so long as the name or package change is documented in Upgrade Notes" Otherwise we may need more voices chiming in, or to put our search for consensus here on hold... Best, Jason On Wed, Nov 5, 2025 at 10:03 AM David Smiley <[email protected]> wrote: > > Thanks Jan :-) > > I love the idea of a dev-docs/deprecation.adoc, perhaps generalized to > backwards compatibility in general. > > On Wed, Nov 5, 2025 at 9:14 AM Jan Høydahl <[email protected]> wrote: > > > Hi, > > > > I think it boils down to this: > > David has stepped up and done a tremendous job in improving SolrJ, and > > gets to choose how. > > We as spectators should applaude, not bike shed. > > > > Bravo David! > > > > The general discussion about when/how to @Deprecate, javadoc @deprecate, > > shim, update ref-guide release-notes, add/remove @lucene.experimental etc > > is an interesting discussion, and is perhaps better had in a dedicated PR > > on a new dev-docs/deprecation.adoc document? > > > > Jan > > > > > 5. nov. 2025 kl. 14:39 skrev Gus Heck <[email protected]>: > > > > > > I think there may have been a misreading of my last message. I'm not > > > advocating that we should shim everything, my point is that deprecation > > as > > > a concept implies the existence of an alternative. Deprecation indicates > > > there is an action that the developer can take. I don't think we need > > > "deprecation" for every little API change. If we know something is going > > to > > > change and want to warn folks in advance we can mark it "@Unstable" or > > > "@Changing" or something like that (think of it as a sort of reversion to > > > @Experimental?). But we shouldn't be using "@Deprecated" (which creates > > IDE > > > warnings and invokes IT Policy) unless we are releasing an alternative > > > concurrently, or the functionality is disappearing entirely. In > > > every case @deprecated javadoc tag (or equivalent annotation/comment/etc) > > > should clearly describe for the developer what the replacement is and > > > possibly point to more information that will help the developer make the > > > transition (like the Jira ticket number or ref guide section?), before > > the > > > current method/class/etc becomes unavailable. > > > > > > Whether or not to shim (or simply maintain two versions of the code > > > simultaneously for a short time), so we can use @Deprecated is a matter > > of > > > magnitude, and impact. I don't think there's a hard rule there. > > > > > > -Gus > > > > > > On Wed, Nov 5, 2025 at 2:32 AM Piotr P. Karwasz < > > [email protected]> > > > wrote: > > > > > >> Hi Jan, > > >> > > >> On 5.11.2025 01:44, Jan Høydahl wrote: > > >>> It is more work to provide a rename or package move if you also need > > >>> to produce shims for the old behavior to work. And in SolrJ for v10 > > >>> we even re-use a previous class name for a differenet purpose, so > > >>> for such a change to work with deprecation we'd need to place the > > >>> new impl in a different package. No wonder some frameworks include > > >>> version in the package name. > > >> > > >> Including a version number in the package name is typically done when a > > >> library is used as a deeply nested transitive dependency, and consumers > > >> cannot migrate to the new version all at once. > > >> > > >> In such cases, you either include both the new classes and shims for the > > >> old ones in the same Maven module (case 5 in JLBP-6 [1]), or you change > > >> the Maven coordinates entirely (case 4). > > >> > > >> Projects like Commons, HttpClient, and Log4j follow this approach, but I > > >> don’t think it’s necessary for SolrJ. For instance, the Elasticsearch > > >> Java Client reorganized several classes in version 9.0.0 [2] without > > >> previous deprecations or shims for old classes. > > >> > > >> Piotr > > >> > > >> [1] https://jlbp.dev/JLBP-6 > > >> [2] > > >> > > https://www.elastic.co/docs/release-notes/elasticsearch/clients/java/9-0-0 > > >> > > >> --------------------------------------------------------------------- > > >> To unsubscribe, e-mail: [email protected] > > >> For additional commands, e-mail: [email protected] > > >> > > >> > > > > > > -- > > > http://www.needhamsoftware.com (work) > > > https://a.co/d/b2sZLD9 (my fantasy fiction book) > > > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: [email protected] > > For additional commands, e-mail: [email protected] > > > > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
