A good tool chain for open source java projects

People give up on plans to open source a project simply because of the logistics of getting it done. Maybe that’s as it should be, basic project Darwinism in operation, but I’m gong to outline a couple hours of work that will get you there. The tool chain outlined here will get you everything you need, and do it in a zero cost, easy to maintain way.

Build Tools

Stick with something simple, mainstream, and IDE agnostic. If you’re open sourcing code you don’t want even building the code to be a challenge. Gradle or maven are the clear choices here. I opt for gradle. I feel like the project files are cleaner and it has more than enough utility to get any job done. Maven does have broader user base but I just find it’s more complex without obvious benefits.

Gradle Users Guide
Getting Started With Maven

Project Layout

Regardless of which build tool you choose, use its standard archetype for your project’s layout. Both maven and gradle have well defined project layouts. Using these will make the project more approachable to others and easy to import into just about any IDE. Don’t innovate here, it will only make your project a special snowflake and your second guessing the tools won’t gain you a thing.

Gradle Java Plugin
Maven Quickstart Archetype

Repository Hosting

GitHub is the best choice here, while there are plenty of alternatives, GitHub is popular for a reason. GitHub will offer a lot of the tools you need, and integrate flawlessly with those it doesn’t. GitHub offers out of the box: issue tracking, project metrics, a project wiki, etc.

GitHub Bootcamp

Continous Integration

If you’ve gone with the recommendations so far, then Travis CI is the way to go. With about five minutes effort, your github repo will integrate into a simple and clean CI tool. Check ins will build and offer a publicly accessible dashboard.

Travis CI: Getting Started

Code Coverage

Along with you CI you can get a coverage dashboard though Coveralls. A few tweaks to your build script and Travis CI can feed coverage data from Cobertura or Jacoco to Coveralls.

Coveralls Gradle PlugIn
Coveralls Maven PlugIn

Artifact Distribution

If you project is genuinely useful, then you should be distributing binary artifacts as well as making the code available. Getting artifacts into the maven Central Repository gets others universal access to your work. Sonatype or Bintray offer simple routes to stage and deploy to the Central Repository. While Bintray touts itself as simpler, it requires you be setup in Sonatype first, and that’s the trickiest part of Sonatype really.

The Sonatype OSSRH Guide
Enjoy Bintray and use it as pain-free gateway to Maven Central

Project Site

GitHub offers gh-pages, it’s a bit of a Rube Goldberg solution, but it offers you a really easy way to create a website associated with your project. The content is just kept in a branch of your project, and then that content is accessible on an industrial strength web infrastructure. They even offer rudimentary content tools, I don’t use those though (see below).

GitHub Pages

Javadoc Hosting

I used to just maintain these on my project site but then I came across www.javadoc.io. This site will automagically pull your javadoc from maven central and vend it up for you. Nice time saver.


Content Presentation

Obviously you can go a million directions on how you layout and present your project sites content. That said one really simple and decent looking solution is Ditto. With ditto you’ll just tweak their basic example, and then drop additional content into fixed locations. It has really good support for content in Markdown format too which makes life easy.

Ditto Home

Example Projects Using This Tool Chain

So all my active open source projects use this tool chain. These are some of my kata projects using it:

Almost Functional
Functional JDBC
JDK Contract Tests