When building a house, you should start with a strong foundation. Similarly, creating a new open-source project requires a certain level of organization!
Roughly, here is a base minimum that makes for a decent project:
- A version control system: having it is a must-have, especially if you’re planning to publish an open-source project!
- A README: help your visitors understand what the project is about and how they can find out more
- A LICENSE: choosing one early informs potential users if they can avail of the project
- A CONTRIBUTING guide: this is not precisely day one stuff, but starting one and updating it as your project develops, encourages outside contributions
- A build tool: regardless of the chosen programming language, you will need a way to manage dependencies and build or redistribute your project as binaries
Any decent build tool should be able to support:
- subprojects or modules
- code formatting
- static code analysis
- global versioning scheme
- generating sources and documentation
- running tests
- enforcing a coding standard
Let’s look at all of these in detail below.
Version Control System
Most projects today use
git hosted on GitHub. Other options exist, but they are beyond the scope of this article.
To create a new repository, take the following actions:
- Create a new organization: https://github.com/account/organizations/new?coupon=&plan=team_free
- Create a new repository
- Choose a license (I chose MIT because it’s permissive; doing so will create a
LICENSEfile in your repository)
- Here’s the result: https://github.com/props-sh/props
Basic repository information
At the very least, provide essential information, in a
README, that helps your users understand what the project is about, how it can help them if they can use it, and how they can contribute to it.
LICENSE file informs potential users about the conditions under which they can use your project. This article doesn't aim to inform about all differences between various types of licenses, but you can read more about it here.
CONTRIBUTING guide will help potential developers open PRs and collaborate in your project.
And now, let’s get to the ‘meaty’ part.
I started by installing SDKman! and then Gradle:
sdk install gradle.
I use IntelliJ as an IDE, and it has full support for Gradle using Kotlin DSL.
Next, let’s configure a sound basis for a Java library made up of multiple submodules.
Root directory configuration
I’ve set up this project as a multi-project build.
I started by creating a
settings.gradle.kts file, which defines a name, and the
pluginManagement/repositories section, which represents a set of artifact repositories to use in all (sub) projects.
rootProject.name = "props"
Define a global version for all dependencies
I created a
build.gradle.kts file and defined a
group = "sh.props"
version = project.version
The version is implicitly loaded from the project and can be specified in a
or by passing it via the command-line, e.g.,
gradle -Pversion=0.3.0 ...
Create a subproject
IntelliJ can easily create subprojects:
- right-click the project and select New Module
- or press Cmd-N
- select Gradle Java module
- fill in the details and you’re good to go!
Alternatively, create a new directory and inside of it:
- create a
- create a Maven-like directory structure:
Include this subproject in the
Set a java toolchain version
Edit the subproject’s
build.gradle.kts file and define the following block to set the Java version to 11.
// additionally also allow incremental builds, speeding up build speed
options.isIncremental = true
Generate source JARs and Javadocs
props is a library, I wanted to generate source and documentation (Javadoc) JARs.
Luckily, this is super easy to do in Gradle. Again, edit the
I chose the JUnit 5 (Jupiter) framework, for which we need to set up a few things:
First, define a new task that will run the tests when called
// Use JUnit Platform for unit tests.
// limit heap usage to 1G (can we tweaked later)
maxHeapSize = "1G"
As well as the necessary dependencies:
libs.junit.jupiter.api notation represents type-safe project dependencies in Gradle. These are defined in the root project settings; see below.
Define a version catalog
Version catalogs are an incubating feature and must be explicitly enabled.
settings.gradle.kts file and add the following section:
// enable the incubating feature
// define the version once
// then create aliases to each component, referencing the version above
Once the above is done, any tests deployed in
**/src/test/java can be run by executing
As a codebase grows, it’s essential for the code to ‘look’ the same, as it helps give developers a consistent experience.
The chosen format (style) is less important than doing this from early on. After all, you can always change the style and reformat the codebase in one go later on!
This is, in my opinion, best done by a tool that indiscriminately auto-formats your code (as you write it)!
Gradle has a great plugin for this: spotless.
Define the plugin’s version in your
And add the following configuration to your
// generic formatting for miscellaneous files
target("*.gradle", "*.md", ".gitignore")
// chose the Google java formatter, version 1.9
// and apply a license header
As you can see in the comments, it formats Java files as well as other extensions.
For Java, it uses the google java formatter and also applies a license header to every file. The
props.license.kt contains a copy of the
LICENSE file with a few tweaks:
- the text is a comment block: (
/* ... */)
- and the year is programmatically filled in: (
Copyright (c) $YEAR Mihai Bojin
Permission is hereby granted...
Check formatting with
gradle spotlessJavaCheck or apply it with
Checking that a project’s coding standard meets minimal quality criteria results in better code!
For this I use
checkstyle, which is also very easy to set up with Gradle:
Add the following to settings.gradle.kts:
// make a global version available
Then edit the subproject’s
// will use the version declared in the catalog
toolVersion = libs.versions.checkstyle.get()
Run the check with
Smarter static code analysis
Finally, the last component I’ll be talking about in this article is
errorprone, a library built by Google that performs smarter static code analysis. Apart from being a great standalone mistake finder, it also integrates with other projects such as NullAway, a tool that helps developers find and fix
NullPointerExceptions in their Java code.
Start by adding the plugin to your
And then add the following configuration to your subproject’s
// hook up the checker to the compilation target
Hopefully, this tutorial gave you an idea of the first steps you should take towards starting an open-source Java library on GitHub.
So far, I only spent a few hours learning how to do all of these from scratch and had a lot of fun doing it!
Since I haven’t ported over any code from the v1 repo, I have probably yet to smooth out all the rough edges. If you end up using it, ping me on Twitter and tell me how you got on! (I’d appreciate it!)
You can find all the code referenced above on GitHub in the props project!
Stay tuned for more articles in this series, and don’t forget to subscribe to my newsletter! I’ll be sending regular updates as I write more code.
Thank you and until next time!