publish javadoc and jdiff reports

[codefromthecrypt]

From @adriancole on May 30, 2016 0:4

Currently, we package, but don't publish javadocs or jdiff reports

javadocs

This is a bit of a problem because there's often good javadocs these days, but pointing to source isn't helpful as they aren't rendered. I'd prefer to be able to refer to javadoc links as opposed to source lines.

jdiff

we don't "do jdiff" yet, but it is a tool to report api differences. Now that we are 1.0, we ought to be able to answer the question of which apis have changed or not.

Example implementations

both of these tools are used in guava, and they setup a build step to publish them https://github.com/google/guava/blob/65e6bd2efb54b9f6a94de0771db698cea8d2a1ca/util/update_snapshot_docs.sh

Copied from original issue: openzipkin/zipkin-java#253

[codefromthecrypt]

cc @eirslett @kristofa @abesto

[abesto]

Both sound like worthy causes. I'll have limited internet access over the weekend, also No Man's Sky was just released, but I'll look into this late next week (unless someone beats me to it).

[codefromthecrypt]

I'd conserve your internet for No Man's Sky :)

[abesto]

I'll have limited access to my PS4 as well, so that won't be an issue :)

[codefromthecrypt]

jdiff I think is still a neat idea though not sure if anyone else feels like this :) If we did it, we should exclude the "internal" package and any package-private types and methods as they are inherently internal. I know some tools show changes to non-public symbols as drift..

If you want jdiff, upvote this? or maybe we should open a new issue? wdyt @jorgheymans

[jorgheymans]

I can generate a few jdiff reports to see what it would look like. What packages / repositories should i include ?

[codefromthecrypt]

first could be "io.zipkin.zipkin2:zipkin" and only the public non-internal types (and symbols inside them). I've struggled in the past getting jdiff to ignore internal things..

maybe after that we can roam to others?

[jorgheymans]

having looked a bit at this, the simplest no-code way to generate a jdiff report between 2 arbitrary zipkin versions is (thanks to our friends over at https://github.com/zolyfarkas/spf4j/) :

$ wget https://search.maven.org/remotecontent?filepath=org/spf4j/spf4j-jdiff-maven-plugin/8.8.1/spf4j-jdiff-maven-plugin-8.8.1-uber.jar -O jdiff.jar
$ java -jar jdiff.jar -gId io.zipkin.zipkin2 -aId zipkin \
-fromVersion 2.10.0 -toVersion 2.15.0 \
-o . \
-p 'zipkin2 zipkin2.storage zipkin2.codec zipkin2.v1'

Only thing i had to do is hardcode the packages to include because it does not have an exclude option to handle zipkin2.internal. I figured this is ok because this really is not a volatile package structure.

If we agree this is a good way to proceed we should hook this into the release process somehow, publish the result and make it available somewhere off README.md

For reference, here is how guava does it - slightly more involved.

[codefromthecrypt]

output looks good to me @jorgheymans ! thanks

[codefromthecrypt]

ps for verification (manually) you can look at our bnd.bnd files as they mention the packages we consider apis.