raphw
Document recommendations for API stability and vendoring
Hello, is there any documentation on the level of API stability provided by bytebuddy, and on recommendations around shading/vendoring it?
I've seen some related discussion on specific issues (e.g. https://github.com/assertj/assertj-core/issues/2470), but it might be helpful to have a brief note on the homepage or something.
I'm having a related discussion here about the possibility of unvendoring a bytebuddy dependency in another project: https://lists.apache.org/thread/sdp7tpvy5n1jlk3g8wqqp40dlyzp5llv
Hi,
with 50 million monthly downloads API incompatibilities are normally reported by the same day. I avoid them for this reason and work with deprecation. I also use a tool that fail the build on introduced inconpatibilities.
my recommendation is to avoid shading, this makes it easier to update what is often needed to support a newer JVM without demanding that directly used dependencies need to be pulled upwards.
This is unless you rely on ASM directly as I do not controll it or if you create an agent. This is mentioned on the webpage somewhere but I'll see to make it clearer.
Thanks!
One note about ASM--I understand that ASM is separate and not in scope for Byte Buddy's API stability guarantees, but ASM has it's own guarantees, so using ASM directly isn't necessarily a reason for shading. From https://lists.apache.org/thread/80wwxmv1totwx5y84w4jzqsh904k8d03:
ASM ensures backward compatibility since ASM 4 in Oct 2011. For instance, the visitMethodInsn signature change in ASM 5 was done in a backward compatible way. We have tests using https://wiki.openjdk.java.net/display/CodeTools/sigtest to ensure that we don't break backward compatibility, and a framework to ensure this when adding new features (https://gitlab.ow2.org/asm/asm/-/blob/master/asm/src/main/java/org/objectweb/asm/Opcodes.java#L64; see also https://asm.ow2.io/asm4-guide.pdf Chapters 5 and 10). Thanks to the Opcodes.ASMx constants and "api' constructor parameters, several tools using different versions of ASM can all shared a single ASM jar providing the most recent version. Each tool will only see the features corresponding to the ASM "api" value they use in their source code. So yes, I think shading should no longer be needed. The only issue is if you use a tool using a very old version of ASM, before ASM 4.0, which is incompatible with ASM 4 or more.
That's true but from practice I still see ASM 3 flying around that has incompatible API. Especially when BB is used for tooling that aims for older JVMs, this is still an issue.
On top of that, stopping to shade would now be an incompatibility introduced by me, so I am kind of stuck with it.
That makes sense, I was thinking about it more from the perspective of someone depending on bytebuddy and also using ASM directly, and trying to decide whether they needed to shade bytebuddy, ASM, or both.