One other thing I suppose should be noted. @deprecated should always be accompanied by an *already available* alternative. Thus, by the standard you are suggesting, simple rename refactors would need to be 2 steps. First release the new methods, then later (in major version) take away the old ones.
Jan, Is that what you mean to suggest in the case of 1:1 method renames with no functionality change? Such a change does break compilation, but it's a trivial fix (if properly documented). I think it's understood through this entire conversation that back compat breaks are a "major version only" prospect, but the question is where to draw the line on deprecation vs simply changing it at the major version boundary. -Gus On Tue, Nov 4, 2025 at 5:54 PM Jan Høydahl <[email protected]> wrote: > SolrJ is part of our user-facing contract, and imo any breaking change > that will make the user's code no longer compile (such as package change) > needs a deprecation, and wait until next major to execute. > > Code changes that will affect 3rd party plugins such as request handlers, > update processors, query parsers etc should also be reserved for major > versions. > > It would not be a crisis in my eyes if we forget to @Deprecate some class > before it is modified in a major version, or if not every single Java level > change is mentioned in ref-guide, since users are extra careful on major > upgrades and expect some churn. > > Jan > > > 4. nov. 2025 kl. 16:38 skrev Jason Gerlowski <[email protected]>: > > > > Hey all, > > > > I was hoping to get a few more eyes on a question that came up > > recently in a JIRA discussion David and I were having. [1] > > > > In short: do we require a deprecation prior to moving a user-facing > > SolrJ class into a new package on "main"? How about when a SolrJ > > class is renamed? > > > > Technically both *are* breaking changes - in both instances it'll > > cause broken compilation of folks' SolrJ code after a version-bump to > > (e.g.) Solr 10. A deprecation warning in (e.g.) 9.9 would give users > > a chance to switch over to the new name before compilation breaks > > entirely, which is a (slightly) better experience. > > > > But on the other hand, this sort of deprecation clearly isn't as > > actionable (and you could argue, "valuable") as one that warns users > > that a feature or class is going away altogether. Additionally, it > > looks like we haven't worried too much about this in practice. For > > example, much (all?) of the "split-package" work that's been done in > > the last few years was done without deprecation warnings, and relied > > solely on "Upgrade Note" entries instead. [2]. That does seem to > > cover much of the gap. > > > > What do you all think: require deprecation? no deprecation? case-by-case? > > > > If there's any consensus on this, I can write it up and put it in > > dev-docs somewhere? > > > > Best, > > > > Jason > > > > [1] > https://issues.apache.org/jira/browse/SOLR-17562?focusedCommentId=18035152&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-18035152 > > [2] https://issues.apache.org/jira/browse/SOLR-16040 > > > > --------------------------------------------------------------------- > > 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] > > -- http://www.needhamsoftware.com (work) https://a.co/d/b2sZLD9 (my fantasy fiction book)
