Home

Welcome to the modern-java-practices wiki!

Go and try it! ← for developers

Note

This project's wiki is the size of a small book or pamphlet, all written in Markdown including any diagrams.

If you'd like to see other ways to leverage your project wiki: https://github.com/binkley/wiki-docs. This applies not just to wiki pages but also to your README.md: you can apply all formatting rules for wikis to your "front door" for your projects.

---

Try it

You should "kick the tires" and get a feel for what parts of this project you'd like to pull into your own projects and builds. You run across lots of projects: Let's make this one helpful for you.

After cloning or forking this project to your machine, try out the local build that makes sense for you:

$ ./gradlew build  # Local-only build
$ earthly +build-with-gradle  # CI build with Earthly
$ ./mvnw verify  # Local-only build
$ earthly +build-with-maven  # CI build with Earthly

Notice that you can run the build purely localy, or in a container?

I want to convince you that running your builds in a container fixes the "it worked on my machine" problem, and show you how to pick up improvements for your build that helps you and others be awesome.

See what the starter "run" program does:

$ ./run-with-gradle.sh
$ ./run-with-maven.sh

A "starter" program is the simplest of all possible "smoke tests", meaning, the minimal things just work, and when you check other things, maybe smoke drifts from your computer as circuits burn out[^1].

[^1]: No, I'm just kidding. Amazon or Microsoft or Google cloud would have quite different problems than "white smoke" from computers[^2].

[^2]: Actually, this really happened me in a data center before the cloud.

---

Introduction

Hi! I want you to have awesome builds 🟢. If you're on a Java project, or a project on any JVM language (Clojure, Groovy, JRuby, Java, Jython, Kotlin, Scala, et al), this article is for you. This article assumes you are using Gradle or Maven for your build locally, and in CI. Some of you are using other build systems native to your source language. Please follow along!

What is the goal of this article? I want to highlight modern practies in building Java/JVM projects with Gradle or Maven, and provide guidance, or at least food for thought. The sample Gradle and Maven projects use Java, but most recommendations apply to builds for any JVM language. I'll never be as clever or as talented as why the lucky stiff, but I hope writing this makes you, developers, and others happy.

See the wheel to the right? No, you do not need to be agile! (But I encourage you to explore the benefits of Agile.) This article is for you regardless of how your team approaches software. The point is to "make people awesome" for any project, possibly the most key value of the Agile approach to software.

Principles for your build

0. Build agreement
   • Is the team onboard with your software build practices?
   • Do stakeholders understand the broad picture and agree?
   • Does the build contribute to meeting project goals?
1. Make it work
   • Can I build deployable software that I believe in?
   • Can I as a Day 1 developer build the project locally?
   • Can I hand the project off to someone else to try?
2. Make it right
   • Can I reproduce issues in the CI build, and fix it locally?
   • Can I find code and security issues from running the build?
   • Is the code clean? Am I happy to explore the project?
   • Do I have metrics on the build I can use to drive improvement?
3. Make it fast
   • Can I run the local build as frequently as I like, and be productive?
   • Can I have a fast cycle of code & test? What about red-green-refactor?
   • Can I update my dependencies and plugins quickly and easily?

Goals for this project

• A containerized[^3] build that I can run on my laptop and in CI so I have confidence in the results, and can deploy to production for real users of my work.
• Shift problems to the left ("to the left" meaning earlier in the development cycle). You'll get earlier feedback while still having a fast local build. Time spent fixing issues locally is better than waiting on CI to fail, or worse, finding problems when production fails.
• Starter build scripts for Modern Java/JVM builds in Gradle and Maven, helpful for new projects, or refurbishing existing projects
• Quick solutions for raising project quality and security in your local build
• The article focuses on Gradle and Maven: these are the most used build tools for Modern Java/JVM projects. However, if you use a different build tool, the principals still apply.

[^3]: This is the most technical goal, and discussed throughout. Think "Docker" for my build.

I want to help with: I am in Day 1 on my project: How do I begin with a local build that supports my team through the project lifetime? And how do I make others awesome on an existing project?

Make people awesome (that means you). This project is based on the experiences of many, and experiments with Modern Java/JVM builds, and shares lessons learned with you.

---

Recent significant changes

Important

I'm summarizing changes but without links to commits, and that does not help the reader. TODO Add commit links for each significant change pointing out which last commit did not require the change.

Tip

Programming is a lot about moving fast, and documentation might lag. I find it successful with delivery teams to include a "task" for a given features (how you do this depends on the tech for your card/task tracking) to include updating your documentation.

• Move sections from README.md to GitHub wiki pages. This is for breaking up an overlong (14k words and counting) README into digestible sections.
• Batect: Remove support for Batect as the author has archived that project. Please use Earthly for local containerized builds. I'll be researching other options, and updating to show those and examples. Advice remains the same: Run your local build in a container for reproducibility, and have CI do the same to exactly repeat your local builds.
• This project uses JDK 21. Here is the previous commit using JDK 17
• Gradle: build with Gradle 8.x.
• Gradle: remove use of testsets plugin for integration testing in favor of native Gradle. This is in support of Gradle 8 and may be helpful in seeing changes you need for Gradle 8 support.