Template for an Open Source Java project

All the following dependencies are free provided your project is Open Source.

• Source repository and VCS

  We use GitHub. Of course you can use another VCS here. What is nice with GitHub is the integration with Travis CI (see below). So here you only have to create a repository.

  Structured commit messages help in understanding changes, and perform automated tasks such as generating changelogs. We propose to follow the Angular JS commit guidelines (see also the variation given here).

  In order to follow easily these guidelines (conventional format) you may:

  • install and use the commitizen command line utility, i.e., use git cz instead of git commit -m "...". The adapter we use is cz-conventional-changelog.

  • install and use the clog command line utility to generate change logs from commit messages that respect the conventional format.

  If you use to work with several projects at the same time, you may consider using the uncommitted command.

• Continuous Integration

  We use Travis CI and its connection to GitHub. See here how to activate this for your project. Then, the provided .travis.yml and build.gradle files will do the job.

• Issues

  We use Github to manage issues. See here for a documentation on Github issues.

  We use the scheme proposed by Mediocre Laboratories for labels:

  • priority: high (#b60205), priority: medium (#fbca04), priority: low (#0e8a16)

  • type: bug (#e99695), type: technical debt (#fef2c0), type: feature (#c2e0c6)

  • other labels, including "duplicate", "wontfix", "invalid", "ready", and "in progress", start by ~, e.g, ~ready (#ededed)

  See here for the list of labels.

  To follow your issues (and the work on them) you can use one of:

  • Github Project Boards
  • Trello, and see here for the integration between Trello and GitHub
  • Waffle, and see here on how to integrate Waffle to your project.

• Code Analysis

  We use Codacy for code analysis. See here how to activate this for your project.

  You may also use SonarQube for code analysis. For this we use sonarcloud.io. See information here on how to setup Travis CI to work with SonarCloud.

• Test Coverage

  We use JaCoCo to produce test coverage reports. For the time being it does not support excluding private constructors from the analysis. Hence you won't get 100% coverage in the reports if you use them (e.g., in order to have a good SonarQube technical debt). To have JaCoCo support, nothing to do, the provided .travis.yml and build.gradle files will do the job.

  We use Coveralls and Codecov to produce test coverage history and statistics. See respectively here, and here how to activate this for your project. Then, the provided .travis.yml and build.gradle files will do the job.

  Coverage information can be sent to Codacy (soon ...)

• Logging

  We use Apache Log4j 2 for logging. A very basic set configuration files, in YAML format, is provided. More information is here. Note the use of distinct configurations files for the run (src/main/resources/log4j2.yml) and for the test (src/main/resources/log4j2-test.yml). This enables you, e.g., to log different things and present them in different ways in test or in production. Of course different logging APIs can be used instead of Log4j. For example if you use java.util.logging you can remove the Log4j and jackson-dataformat dependencies from build.gradle, and you don't need the Log4j configuration files.

• License Badges

  We use shields.io to generate the license badge automatically from the LICENSE file in the github repository.

• Tags and Releases

  see Git Basics - Tagging and GitHub Help - Releases.

  We use shields.io to generate tag and release badges automatically. Note: this seems to fail for releases for some reason. If tags and releases correspond, you can use the last tag badge and use the label parameter to change the badge label.

  • last tag:

      https://img.shields.io/github/tag/pascalpoizat/template-java-project.svg?style=flat-square
      

  • last release:

      https://img.shields.io/github/release/pascalpoizat/template-java-project.svg?style=flat-square
      

  • last release (including a pre-release):

      https://img.shields.io/github/release/pascalpoizat/template-java-project/all.svg?style=flat-square
      

• Documentation (soon ...)

• Web Site (soon ...)