Clarify version auto-increment situations and versioning workflow

[magneticflux-]

I became a little bit confused reading the documentation on the auto-increment feature. It states that the version is incremented when "there are changes in the binaries when compared to previous version"and that "There are multiple options how to deal with version bumps", but it only gives some vague examples. I can see that the PATCH number incremented when I change minor things, but does the MINOR number increment when the artifact's public API grows and the MAJOR number increment as the public API shrinks (as in SemVer)?

I'm looking for a comprehensive list of all the ways (and hopefully the recommended way) to increment a project from the 0.0.X stage to the 0.X.Y or X.Y.Z stages.

[wwilk]

Hello. Good question! I will make sure that we extend this part of the documentation.

At the moment we only automatically update the PATCH part. If you want to update MAJOR or MINOR you need to do it manually in the version.properties file.

Also we only update PATCH if there were any changes in binaries. See this task for details. Basically, we only do it if you make a change in resulting binary (eg. production code change) or one of its dependencies. It doesn't make sense to release if you only change eg. .gitignore or fix a unit test.

From the beginning we are thinking of a way to do it automatically for all of them. We haven't found any simple and elegant solution yet. Do you have any suggestions how it should look like?

[magneticflux-]

Thanks for the quick response! Okay, that's understandable!

As far as detailed jar diffs go, have you looked into getting all publicly visible ASM data from the jars? If you had a set of all public API "things" (methods+sigs, classes, variables), you could perform union / intersection / whatever operations on them to find changes. That would ensure that even the smallest change, like modifying a public method's signature would correctly increment the version to prevent any compatibility issues. I searched a little bit for some tools that do that and found scala/jardiff, but that seems to output ASM text rather than POJOs representing structured ASM data.

[wwilk]

We already compare sources jars, basically we just compare each file with its previous version, so any change in code (like modifying a method's signature) will be discovered. We don't use external tools for that, just a simple comparison of the content of files. You can see ComparePublications and ZipComparator for details. It seems that it works fine, but if you think that it misses some edge cases than we are open to suggestions!

[magneticflux-]

I investigated a suggested library and shared my findings here: https://github.com/mockito/shipkit/issues/105#issuecomment-353092660. I think it shows a lot of promise! Unfortunately, I don't have much Groovy/Gradle plugin experience right now so I'm a bit reluctant to take a shot at replacing your current method since it's working well enough currently.

[wwilk]

But in this comment you mentioned you are talking about Japicmp, and here about scala/jardiff?

What would be the benefit of using scala/jardiff comparing to what we currently have? The tool looks good, although I think:

• it's more readable for the user if the diff is done on sources, not bytecode IMHO
• seems that it's mostly command line tool and it's not in maven central which makes it harder for us to include it in the project
• it's an additional dependency, we want to keep Shipkit small

Thanks for your interest in the project! Maybe you want to take a stab at one of easier issues in Shipkit to get some Groovy/Gradle experience ?:) I would be happy to help!

[magneticflux-]

Sorry, I wasn't very clear. I initially thought scala/jardiff would work, but Japicmp looks like a much better fit so I retract my initial statement.

Thanks, I might give it a shot!

[mockitoguy]

Nice discussion! Can we close this ticket or this is something we want to formally document?