Java release engineering good practices

| | August 7, 2015

I’ve got a fairly simple open-source Java project I am starting. This process is new to me, I’m used to writing programs just for myself. What are some good practices to be aware of when releasing open-source projects in Java?

Here are some things I can think of, can you suggest others?

  • version control repository (what do you use to explain relevant tags/branches? an external README file?)
  • include appropriate open-source license in code
  • include prepackaged executable JAR file, including version number in the filename
  • some kind of README file that explains external dependencies needed to build/run the software (is there a common convention for what filename and where to put it?)
  • a webpage for the project, w/ a link to it in the source code and/or executable, in case someone obtains the source code or executable first (rather than through the webpage in question)

7 Responses to “Java release engineering good practices”

  1. I know Maven is already mentioned, but I think that even more important than using Maven is to publish artifacts to Maven repositories, so that projects that do use Maven can use them.
    Your project page can then provide direct links to a repo as well so it server as storage space for downloadables as well.

    Also: in similar vein, making jars OSGi bundles — which just means adding a few Manifest entries, nothing very complicated — is another good thing.

    Both of these help others to more easily add dependencies to your package (if applicable) and can help adoption.

    Some more things to consider:

    • Sensible version number scheme (major version bump for incompatible changes; minor version for additions with backwards compatibility; or something like that)
    • Keeping good release notes
    • Use a bug-tracking system, if you can use one easily (Codehaus,, SourceForce etc all offer this)
    • Simple project Wiki for documentation
    • Mailing lists for discussion
  2. Basically you want your project to work ‘out of the box’. When people are choosing the right open source project for a task, they download a bunch of projects that say they support the task, and use the best one. If a project needs significant work to setup (e.g. downloading 20 JAR dependencies from 20 different sites) most people will only either try it as a last resort or just ignore it.

    Repository: You might try some newer repository engine – like Mercurial or Git. They ease development and ease merging of branches. Importantly though, choose an engine that is supported natively by your IDE.

    Dependencies: You should use a readme to state dependencies, but this is not sufficient, either use Maven to manage dependencies, in which case you just need to include pom.xml file, or include JARs that you are dependent on in your distribution. In second case divide dependencies into mandatory, optional, compiletime and test. An example of an optional dependency are the bytecode generation tools for Hibernate.

    Site: Maven may create a site that is associated with particular version of your software (never used that though).

    Documenation – JavaDoc: Document everything, and try to enforce a policy that ensures high quality javadocs:

      * Sets the cost
      * @param decimal cost 
     public void setCost(BigDecimal decimal){

    is useless. Better is:

      * Sets the cost, cost is in currency setted by #setCurrency. 
      * @param decimal cost, precision shoule be at least three places
     public void setCost(BigDecimal decimal){

    Documentation: Javadoc is not enough. Give some starting point – a tutorial is preferable (and I don’t mean the kind of tutorial with many screenshots of eclipse dialogs ;)). Example code is OK too, or at least write somewhere – ‘Reading the javadoc of the EntryPoint class is a good way to start using this library’. If you have only javadocs anyone who is considering using your library will be presented a list of all the clases and packages, and will not know where to start.

    Bugtracking Software: You won’t remember more that three bugs at a time (and will forget things) – also it will help you manage tasks, and new wanted features.
    You may want to try:

    • FogBugz – its nice, but costs money. (Free for up to two developers).
    • Bugzilla – nice, popular and free

    Project Management Software: This will help you to calculate release dates, split tasks between developers etc.

    Try to pass Joel test

    Build process: Make the build a one-click process. For example an ant script that increments the version number, launches maven builds, deploys the site and so on. Worth the effort!

    Forum: A nice idea, will help support.

    Wiki: In many (even quite developed) projects such wikis are rather empty which is bad (as it makes people think ‘how can this be great software if no-one writes in this wiki’).

  3. Valentin Rocher on November 30, -0001 @ 12:00 AM

    You could also use Maven for releasing your code. With it it’s quite easy to create a site for your project, specify the dependencies, optimize the releases…For example, the Commons projects at Apache use Maven.

  4. I suggest using MAVEN as tool for managing external dependencies needed to build/run

    You can aslo use Vulcan or alike for continous inetgration, so it is known whetaher current version is realy working or not.

    1. Plan on developing some type of website. If your code involves web software, people really marvel if you are using it as part of your site.

    2. Developers love good documentation and lots of samples. I have seen projects that have lots of powerful code but 0% documentation fall hard.

    3. Having a wiki setup to let people write ideas and recipes is a definite plus. (I recommend mediawiki).

    4. A forum to post ideas, threads of discussions, i.e. a community forum is also good.

    5. Setup a mailing list and encourage people to join.

    6. Post real updates to your mailing list, wiki site, and also as news on your main site to show you are really working on things. Encourage participation. Make yourself available. This all generates a sense that you are interesting in chipping in, and that you are open to input from others.

  5. One thing you should definitely do (because it’s Java) is to generate Javadocs for your code. This means commenting classes and methods using the Javadoc notation for easier readability to others.

  6. Generate a ChangeLog from checkin comments. Separately create a release note explaining what you fixed/added in each release.

Leave a Reply