Reusing this project

Reusing this project

Don't forget to fork me or clone me! It is licensed under Creative Commons 0 Public Domain Dedication. If you fork, take care that upstream pulls work; I'd like to hear from you if you have trouble with forking.

Sensible approaches:

• Fork this project, and work from there. You are using this project as a starter. Keep an eye on improvements (usually version bumps on tools and dependencies) that may apply to you. Watch the wiki pages that interest you most: the wiki is continually updated.
• Clone this project locally if you want to contribute).

If you cloned this project as a starter, keep up-to-date on improvements:

git remote add upstream https://github.com/binkley/modern-java-practices.git
git fetch upstream
git merge master/upstream

Once you are happy with your project, you should think about removing the upstream remote, and reviewing changes in this repository by hand. Your decision might depend on what merge conflicts you encounter.

Non-obvious relevant files

• build-as-ci-does.sh — Helpful when CI has steps that local developers do not, and you want to reproduce or explore locally a CI problem. The script should match the actions your CI takes on pushes (this project uses GitHub actions).

  It is smart enough to check if you have gh act available, and run your workflows locally, otherwise directly call earthly.

  An example is adding new artifacts to save in CI:

  1. Update Earthfile to save the new artifacts (SAVE ARTIFACT command).
  2. Remove completely the local build/ (Gradle) or target/) directories.
  3. Run earthly via this script and check for a clean build.
  4. Check that target locations in Earthfile get created.
     For simple cases of 1-to-1 copy/naming, check the build/ (Gradle) or target (Maven) local directories that the build copied the expected files.
  5. If no files are expected, there should be no build/ (Gradle) or target/ (Maven) local directories after running the script.

Irrelevant files

This project includes files which are helpful for maintaining itself, but may be irrelevant to you. Some, however, may prove helpful in specific contexts as noted:

• coverage.sh Checks if the local code passes at given levels of code coverage. The script is focused on Maven, but with edits would do the same for Gradle. This supports the "ratchet" pattern.
• run-with-gradle.sh — If you are a Gradle project, you will likely rename this to just run or similar.
• run-with-maven.sh — If you are a Maven project, you will likely rename this to just run or similar.

Tips

• Before pulling from upstream do clean up your local build to avoid mixed results from different code versions. CI does not typically face this issue since it should start fresh each build.
• Consider Clone git repository without history? to start at the current tip of this project. For example, some images in README.md started overlarge in earlier versions, something you may not want in a clone.
• Caution: Not all the images used in README.md may be in the Public Domain or under CC0 (this is challenging to research). Use due diligence before sharing your clone, and other licenses may apply for these images in a global context. We are not laywers.