Thank You for explaining the process and reasoning behind it. It is also good to know the community's attitude towards backward compatibility.
I'll close the current PRs and try to spoon feed changes while optimising for "diff-readability" until we build some trust. On Mon, May 9, 2022 at 11:09 PM antonio <[email protected]> wrote: > Hi, > > Some comments below. > > El 9/5/22 a las 22:17, Łukasz Bownik escribió: > > So I suspect that the probability of any *external client *calling this > > method is 0. > > As we have explained in some other threads, NetBeans is both an IDE and > a platform. We want to be as much backwards compatible as possible. > > Even though you suspect "the probability of any external client calling > this method is zero" (which IMHO is a bold statement coming from a > newbie) and want to remove a method from an API, we still want to be > backwards compatible. > > For making API changes I think the method is as follows [1]: > > 1. Newbies should discuss in the mailing list why they want to change an > API, telling us if it is because "they suspect" the code is used "with > zero probability", or because they've investigated the usage of the API > in other ten NetBeans applications, or any other reasoning. If the > change to the API affects a module that is heavily used (such as this > one) then be ready to reason your change proposal with sound arguments. > > 2. Methods that are to be removed must add the @Deprecated annotation > and won't be removed immediately, there's a grace period for API clients > to have time to prepare for the change. Of course, deprecated methods > should work _exactly_ the same as before the change. > > 3. API changes have to be documented in the `apichanges.xml` file [2]. > > 4. API changes must bump the "specification version" in the module's > manifest.mf file [3]. > > 5. API changes have to update the ".sig" signature file [4] with the new > signature. > > Hope this helps, > Antonio > > > [1] > Read this full thread in the mailing list archive for some other tips on > changing a NetBeans API. > > [2] > > https://github.com/apache/netbeans/blob/master/platform/openide.util/apichanges.xml > > [3] > > https://github.com/apache/netbeans/blob/ddcd57d016b1e801b6a7fba973ae9889d108b1f3/platform/openide.util/manifest.mf#L4 > > [4] > > https://github.com/apache/netbeans/blob/ddcd57d016b1e801b6a7fba973ae9889d108b1f3/platform/openide.util/nbproject/org-openide-util.sig > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > For further information about the NetBeans mailing lists, visit: > https://cwiki.apache.org/confluence/display/NETBEANS/Mailing+lists > > > > -- Łukasz Bownik
