Template for an Open Source Java Project

This is used as a set of information for students' projects.

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

• Source repository and VCS

  We will use GitHub. Of course you can use another VCS here. What is nice with GitHub is the integration with CI, issue management, and project boards (see below). So here you only have to create a repository.

  You must sign your work (commits and tags). See here.

  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, e.g., use git cz instead of git commit -m "..." or use the plugin for your IDE (e.g., see here). 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 will 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.

  You can use other CI services that have equivalent features. We will add information about GitHub actions in a next version of this template.

• Issues

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

  We will 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
  • GitKraken Boards and see here for the integration between GitKraken Boards and GitHub
  • Trello, and see here for the integration between Trello and GitHub
  • unfortunately, Waffle is now out of the game

• Code Analysis

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

  Another solution is to use Code Climate. 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 will 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 (anyway, remember 100% coverage is not an objective in itself). To have JaCoCo support, nothing to do, the provided .travis.yml and build.gradle files will do the job.

  We will use Coveralls and Codecov to produce test coverage history and statistics. See respectively dead link, 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 also be sent to Codacy (more information to come).

• Logging

  We will 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 will 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 will use shields.io to generate tag and release badges automatically.

  • 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

  We will use Asciidoctor and PlantUML. (more information to come)

• Web Site (more information to come)