Make it easy to publish source and api documentation archives

Old Forum
1

Many projects publish their source and api documentation as zip or jar archives that are published to a repository along with their jar. It would be nice to offer a declarative means of doing this.

Implementation ideas

One approach is to extend the java plugin to add ‘sourceZip’ and ‘javadocZip’ tasks. This way, you can easily publish them in your build script:

apply plugin: 'java' // or 'groovy' or 'scala'...
  artifacts {
    archives sourceZip, javadocZip
}

Extra credit

Some ideas to build on this:

  • Add support for groovydoc and scaladoc archives. * Extend the application and java-library plugins to include the source in the distribution, when the source is to be published. * Do the same for api documentation, so that it is included in the distribution, when the api documentation is to be published. * Make this work with ivy repositories.
2

I am going to try and complete this task as a way to get my feet wet with Gradle plugin development. I have a preliminary fix done for the java plugin: https://github.com/AdamRoberts/gradle/commit/f23158c69315e24886082724e6a12b414e34cf6f

But I have some questions before I can finish the java plugin changes and start on the extra credit.

  • Should there be the option to publish a jar archive also? It seems a 50/50 split on if sources are published in a zip or a jar (I am used to publishing in a jar). I know that we would not be able to easily switch from publishing “snapshots” of our source from zip to jar, you could end up with the resolved “source” artifact being out of sync with the “byte code” artifact if the wrong extension was resolved.

  • How many integration tests should be written? I assume that test should be added to ‘subproject/integ-test/src/integTest/groovy/org/gradle/integtests/JavaProjectIntegrationTest.groovy’, but I am not sure to what extent tests are expected, are the integration test mainly to cover happy path, or should they check everything. From the existing tests for the “jar” archive it appears that only the happy path is tested.