Getting your project started

To get a project off to a good start, consider these items. Even for existing projects, you should address these as you go along or while refurbishing an existing project:

• Team agreement comes first. Make sure everyone is onboard and clear on what build standards are, and understands—at least as an outline—what the build does for them
• Provide a good README.md. This saves you a ton of time in the long run. This is your most important step. A good resource is Yegor's Elegant READMEs
  • Intelligent laziness is a virtue. Time invested in good documentation pays off
  • A good README.md answers visitors questions, so you don't spend time answering trivial questions, and explains/justifies your project to others.
  • Fight Conway's Law with communication!
• Pick a version of Java, and stick to it throughout your local build, CI pipeline, and environment deployments. Do not mix versions.
• Pick Gradle or Maven, and use only one. This project provides both to demonstrate equivalent builds for each. See Use Gradle or Maven for more discussion
• Use build wrappers committed into your project root. These run Gradle or Maven, and coders should always invoke ./gradlew or ./mvnw (use shell aliases if these grow tiresome to type)
  • Build wrappers are shell scripts to run Gradle or Maven. The wrapper takes care of downloading needed tools without getting in the way. New contributors and developers can start right away; they do not need to install more software
  • For Gradle, use ./gradlew (part of Gradle)
  • For Maven, use ./mvnw (a plugin)
• Always run CI on push to a shared repository. It's a sad panda when someone is excited about their commit, and then the commit breaks the other developers
  • In CI, use caches for dependency downloads; this speeds up the feedback cycle from CI (see below)
  • When sensible, move code quality and security checks into local builds before changes hit CI (see below)
• Pick a common code style, and stay consistent. Update tooling to complain on style violations:
  • The team should agree on a common code style, eg, SUN, Google, et al
  • See Choose your code style

Showing your project to others

Everyone wants to share their project. This could be just teammates, or stakeholders, or to the public. Key setup in your project includes:

• A good README.md file in the project root (see above reference for "elegant READMEs")
• A solid build that others can see. Initially you expect a mix of green/red builds (passing/failing) as you stablize: this is normal. However as the project gets off the ground, you should expect usually all green builds, and red builds should normally result from experiments with the CI build itself such as trying new features from your CI provider (GitHub, GitLab, ADO, Jenkins, etc).

OK, you have a solid build, a satisfactory README, and you'd like to give quick notice to visitors (other developers, stakeholders, the public) to your project site. They at first glance want to check that the project is solid.

First things to share

Of course the first things to share with others is the link to your project front page. Depending on your circumstances, this is typically the README itself: the purpose is right there in the file name. For this example project, we use https://github.com/binkley/modern-java-practices.

After that, you should share links for project Issues. Depending on the system you use for problem reporting, this is often the GitHub Issues for the source code, but it will vary on your circumstances and may be alternatives such as JIRA and others. For this example project, we use https://github.com/binkley/modern-java-practices/issues.

[!IMPORANT] Especially useful is to let others add new issues/concerns/problems/bugs/feedback. This is one of the best tools you have to capture future changes or requirements that you did not know about. For this project, we use https://github.com/binkley/modern-java-practices/issues/new.

For developers and technical stakeholders, they may want to see outstanding pull requests (PRs) that are waiting to merge into your mainline code. For this example project, we use https://github.com/binkley/modern-java-practices/pulls.

If you use a card wall to manage work, or a task wall, or a problem queue, and so on, best to share that link as well. In a larger scope, this helps other teams or groups or public projects track progress on their concerns. For this example project, we use https://github.com/users/binkley/projects/1/views/1.

And, of course, when sensible provide access to the project source code for others to browse. This is especially helpful to other developers reusing your project, and wanting to see more than formal documentation. (You may be in circumstances where this is restricted.) For this example project, we use https://github.com/binkley/modern-java-practices.

Badges: really make your README stand out

One of the best ways to provide a great README is to show badges: short images that highlight status. An image explains everything:

Note that this example project provides quick visuals for:

• Build status with Gradle — for Gradle projects; provided by GitHub
• Build status with Maven — for Maven projects; provided by GitHub
• CodeQL status — if you choose to use CodeQL in GitHub
• Snyk security status — if you use Snyk security scans
• Code coverage percentile — your coverage; JaCoCo for this project
• Pull request count — provided by GitHub
• Issue count — provided by GitHub
• Licensing — relevant for public projects

You will not likely want all of these, and may have others you'd like to add. A good badge to show is "Release" with a version: this helps others know if they are up-to-date, and the badge points to how to download or use the latest version.

At a minimum you should show:

• Build status
• Coverage checks (if you implement them)
• Issues for a quick way for others to give your feedback and bugs

Look at this project's README.md for example Markdown for badges.

Tips

• Consider using client-side Git hooks for pre-push to run a full, clean, local build. This helps ensure "oopsies" from going to CI where they impact everyone. The options are broad. Try web searches on:

  • "gradle install git hooks"
  • "maven install git hooks"

  This article presently has no specific recommendations on choices of plugin or approach for Git hooks.

Going further

TODO: Placeholder section