Use always latest versions in distribution

[abelsromero]

trafficstars

We are maintaining different versions of the dependencies (asciidoctorj-pdf, asciidoctorj-diagram, ...) for branches main and v2.5.x. For example:

• main uses asciidoctorj-pdf 2.3.7.
• v2.5.x uses asciidoctorj-pdf 1.6.2, but it works perfectly with 2.3.7. The project has some testa already and run fine.

My proposal is to align the distribution with the latest always. So long is compatible there are no blockers.

PS: this was brought here around the update of the docs properties. Related to that, I don't think the properties are used in the docs at all.

[abelsromero]

Answering https://github.com/asciidoctor/asciidoctorj/pull/1223#discussion_r1239803321

Generally, testing the compatibility can be quite difficult, to me it means more than the API compiles, and writing integration tests that cover every possible use case can be challenging. I'd like to use whatever the dependency claims through semantic versioning, if it claims to have a major breaking change, we should also only expose it in a major release. I think that is also the way that other libraries like Spring Boot follow.

Yes, testing compatibility is tricky. I agree that it's more than compiling and that we can at most cover some common scenarios.

But I don't think semver applies here. Following the Boot example, recently snakeyaml was bumped from v1.33 to v2.0 in all branches (v2.7 and v3.x). As a Boot consumer you don't care about third-party dependencies it brings, and that's how I see the other asciidoctorj-* components in the distribution. It's true snakeyaml was a bit of a special case and in general major bumps even for third-party libs are not wanted, but not uncommon either.

Now, maybe the question is how we should deal with this here. It's not a bad idea to lock to the versions to the one on release. So that Asciidoctorj 2.5.0 started with j-pdf 1.6.x, they should go together. But that means we should align them on every AsciidoctorJ release (same for -j-diagram, epub, ...) and keep maintenance branches for j-pdf, j-diagram, etc. which are not there now. That's why I think (for simplicity's sake), that as long we don't have major technical limitations, we should aim to support the latest. Fewer branches and less overall work. In case of a major breaking change, we can always create a maintenance branch on demand, but not as default.

[robertpanzer]

That's too funny, because I had exactly that example on my mind :D While reviewing a PR last week that upgraded SnakeYaml I saw this comment from Andy: https://stackoverflow.com/a/75875594/2779488

However, looking at the release notes for asciidoctor-pdf 2.0.0 it seems like this was only done to mark the official start for going with semver. Let's go for it and look where we end up.

[abelsromero]

Let's go for it and look where we end up.

You were convincing me now, it seems I do not understand Boot policies.

But in the end, I still think we should use the latest to lower our work and cognitive load.