To be clear, we don't guarantee any kind of binary compatibility across major versions (I'm not sure it's reasonable for us to try to offer binary compatibility guarantees across minor versions either). It is expected, therefore, that users will recompile their code to move across major versions, if not also minor versions (bugfix/patch releases should definitely be drop-in compatible, though).
I mention the lack of binary compatibility guarantee for major versions mainly to point out that the process of checking errors one-by-one that you suggested should be something downstream developers do in their IDE or CI environment, and not just being surprised at runtime. Dealing with errors during CI isn't a fun experience, but it's not as bad as being surprised by them at runtime. Migration across major versions is not expected to be effortless. The point of bumping the major version is to signal that some effort might fall on downstream users. That said, I agree there's room for improvement in documenting the details of compatibility-related changes to the API. I don't think documenting them as we go, like you suggest, is sufficient, though. We more-or-less tried to do that with the 2.0 release notes, and did, in fact, mention breaking changes there. However, I think you're suggesting a more dedicated section in the notes, perhaps in a tabular format, rather than mixed in with the rest of the notes. In order to ensure that we don't miss things that broke unintentionally during the development process, or to catch changes where the docs weren't updated as we go, we'd need to run some sort of comparison tool, like previously suggested, even if we had been tracking things during development. There are two ways a comparison tool could be useful if somebody were to find a good one and leverage it to contribute to the project: 1. As a code quality measure to catch breakages that would block a release (or trigger a major version bump for the release). A good time to do this would be during the release candidate voting period, and we encourage anybody interested in specific measures of code quality to participate in that voting process. This is one of many kinds of checks somebody could do to get involved to ensure the project meets their expectations. Contributors with non-binding votes can still provide useful feedback here to affect binding votes and improve the quality of the release. 2. As a communication aid, to generate reports to include in the release notes to inform users of changes. After every release vote, we have a period of several days where we are finalizing the release notes collaboratively on the website, before we announce the release. These release notes can also be updated after a release. This is a collaborative process, and another way somebody could get involved in the project. If a contributor feels the release notes can be better, by including such things, contributing in this area would be a great way for them to get involved. On Wed, Oct 20, 2021, 18:20 Jeremy Kepner <kep...@ll.mit.edu> wrote: > Seeme like there should be document that is kept whereby everytime a > breaking change is made it gets documented at the time it is committed. > > On Wed, Oct 20, 2021 at 04:55:42PM -0400, Christopher wrote: > > If somebody were to volunteer to create such a document, they could do so > > from some of the many 3rd party java API comparison tools. I'm not sure > > which tool would work best for this purpose, though. > > > > If anybody does this, let us know which one worked best for you. We could > > also amend the release notes with whatever you find. That could be > useful. > > > > On Wed, Oct 20, 2021, 15:14 Jeremy Kepner <kep...@ll.mit.edu> wrote: > > > > > There should be a document that clearly states 1.10 functions will not > > > work in 2.0 > > > so folks can grep their code to check. Otherwise you have to install > 2.0 > > > and then just > > > work through the errors one-by-one. > > > > > > On Tue, Oct 19, 2021 at 11:17:09AM -0400, Christopher wrote: > > > > The best reference is the release notes: > > > > https://accumulo.apache.org/release/accumulo-2.0.0/ > > > > > > > > On Tue, Oct 19, 2021, 09:15 Jeremy Kepner <kep...@ll.mit.edu> wrote: > > > > > > > > > Is there a list of things in 1.10 that will no longer work in 2.0. > > > > > > > > > > On Tue, Oct 19, 2021 at 08:59:58AM -0400, Christopher wrote: > > > > > > Hi Vincent, > > > > > > > > > > > > To supplement what Mike said, it's possible some stuff that was > > > > > > deprecated in 1.10 was dropped in 2.0. I don't have a > comprehensive > > > > > > list of what that might include, but anything marked as > deprecated in > > > > > > 1.10 is subject to removal in 2.0. If I recall, we did try to > limit > > > it > > > > > > somewhat. It wouldn't really make sense to create a shim to > restore > > > > > > those APIs, though, because that would just reintroduce code we > > > > > > explicitly dropped, which defeats the purpose of a major version > > > bump. > > > > > > In semantic versioning, the entire point of a major version bump > is > > > to > > > > > > declare a break in the backwards compatibility of the public API. > > > > > > > > > > > > If you need the code that was dropped, you probably aren't ready > to > > > > > > move to 2.x. 1.10 is an LTM release, so that means we intend to > keep > > > > > > patching important bugs until a year after our next LTM (which > hasn't > > > > > > yet been released). So, if you need to stay on 1.10, you have > plenty > > > > > > of time to update your code to stop using deprecated APIs and > avoid > > > > > > non-public APIs. > > > > > > > > > > > > On Tue, Oct 19, 2021 at 8:10 AM Mike Miller <mmil...@apache.org> > > > wrote: > > > > > > > > > > > > > > If the library was written using only the public API then it > > > shouldn't > > > > > be a > > > > > > > problem. See https://accumulo.apache.org/api/ > > > > > > > Accumulo follows SemVer to maintain compatibility of the > public API > > > > > between > > > > > > > versions. There are a lot of changes between 1.10 and 2.0 but > > > anything > > > > > in > > > > > > > the public API in 1.10 should still exist in 2.0, even if > > > deprecated. > > > > > > > If the library is calling internal methods or extending > internal > > > > > classes, > > > > > > > then that is a different story. If it uses internals then I > > > recommend > > > > > > > refactoring to use the public API if possible. > > > > > > > > > > > > > > > > > > > > > On Mon, Oct 18, 2021 at 3:38 PM Vincent Russell < > > > > > vincent.russ...@gmail.com> > > > > > > > wrote: > > > > > > > > > > > > > > > Hello, > > > > > > > > > > > > > > > > I am interested in using an accumulo query and storage > library > > > that > > > > > was > > > > > > > > written against accumulo version 1.10 and I am interested in > > > using > > > > > it with > > > > > > > > accumulo 2.0. > > > > > > > > > > > > > > > > Is there a shim that exists that would allow the library to > be > > > used > > > > > for > > > > > > > > both versions that could be activated at compile time via a > maven > > > > > profile > > > > > > > > or something? > > > > > > > > > > > > > > > > Thanks, > > > > > > > > Vincent > > > > > > > > > > > > > > > > >
