Contributing

Great to see you on this page! It means you are interested in how Checkstyle Addons is built or you are even considering a contribution.

If you’ve got an idea or - even better - some code for a new high-quality check, we should talk about getting it on board. In fact, you can put it on board yourself by creating a pull request for it (more below). The same is true for all kinds of improvements, including improvements to the website.

Current Status

Checkstyle Addons is using the Travis Continuous Integration system. Every push to master and every pull request are automatically built by Travis-CI. If the Travis status is passing, then it was successfully built with different Checkstyle versions, and all unit tests were successful. Test coverage is measured by Coveralls. The badge below shows the current coverage, which is recomputed upon every successful build. Also, the coverage is calculated for every pull request, and reported on the pull request’s discussion page.

Build Status

Build Status Coverage Status
OpenHub Stats

Collaboration Model

Checkstyle Addons follows a Fork & Pull collaboration model, which means that all changes go through pull requests. Please feel free to suggest anything that’s good. If you are going to expend a lot of work, it may make sense to open an issue about it first, so we can discuss your plans.

Building from Source

In order to build Checkstyle Addons yourself, follow these steps:

  1. Make sure you have the prerequisites set up:

    In order to do a full build of Checkstyle Addons, we actually need all three JDKs at the same time. It’s no problem to have them all installed as long as each has its own distinct directory. The build process itself must run on Java 8. It is basically possible to not install Java 6 and Java 7 SDKs, but then the build will not create artifacts compatible with these versions of Java.

  2. Make sure that your environment variable JAVA_HOME points to the Java 8 SDK, for example C:\PROGRA~1\Java\jdk1.8.0_92 (Windows).
  3. %JAVA_HOME%\bin (Windows) or $JAVA_HOME/bin (Linux/Unix) should be first on the PATH
  4. If you don’t have a Gradle User Home yet, set it up by creating an empty directory called .gradle somewhere, for example d:\.gradle (Windows) or ~/.gradle (Unix). Create an environment variable GRADLE_USER_HOME which points to this directory. This directory may grow quite large over time, because Gradle uses it to cache all downloaded stuff. Mine is 3 GB. All Gradle processes, including your IDE, should see this environment variable.
  5. Create an empty text file in GRADLE_USER_HOME called gradle.properties. Inside, add the following lines:

    org.gradle.daemon=true
    org.gradle.jvmargs=-Xmx1536m -XX:MaxPermSize=384m
    checkstyleaddons_jdk6_java=C:/PROGRA~1/Java/jdk1.6.0_45/bin/java.exe
    checkstyleaddons_jdk6_javac=C:/PROGRA~1/Java/jdk1.6.0_45/bin/javac.exe
    checkstyleaddons_jdk6_javadoc=C:/PROGRA~1/Java/jdk1.6.0_45/bin/javadoc.exe
    checkstyleaddons_jdk7_java=C:/PROGRA~1/Java/jdk1.7.0_80/bin/java.exe
    checkstyleaddons_jdk7_javac=C:/PROGRA~1/Java/jdk1.7.0_80/bin/javac.exe
    checkstyleaddons_jdk7_javadoc=C:/PROGRA~1/Java/jdk1.7.0_80/bin/javadoc.exe
    

    The first two lines are optional and may be left out if the build works for you. The other lines basically configure where the executables from the lower version JDKs are at. This is used to build artifacts compatible with previous versions of Java. If these properties are missing, those artifacts will not be created. Adjust the paths depending on where you installed your Java 6 and Java 7 SDKs). The paths should not contain spaces (may still work, but not tested).

  6. Clone the Checkstyle Addons repo by running on the command line:
    git clone https://github.com/checkstyle-addons/checkstyle-addons.git
  7. cd checkstyle-addons
  8. gradlew build
    This will take care of everything needed for a successful build of Checkstyle Addons, including download and installation of Gradle.
  9. Find the fresh artifacts in build/libs. Done!

IntelliJ IDEA Configuration

In case you want to use IntelliJ IDEA as your IDE to develop Checkstyle Addons, you need to make sure that these settings are configured correctly:

Running the Website Locally

Running the website locally is important in order to be able to test changes before they go online. The Checkstyle Addons website is based on Jekyll, GitHub’s lightweight but powerful CMS. The website theme is Thomas Park’s SpaceLab theme, which is based on Bootstrap. Markdown is GitHub-flavored markdown (GFM), processed by kramdown (the GitHub pages standard). Syntax highlighting by Rouge (again, the GitHub standard). It is technically possible to use Jemoji in the bodies of pages and posts. :+1:

  1. Check the prerequisites:
    • Git
    • Ruby 2.2.4 or higher (Windows Installer, Unix/Linux), needed because Jekyll is a Ruby Gem. Choose the 64bit or the 32bit version depending on your operating system.
    • Ruby DevKit, available from where you got Ruby itself (installation instructions)
    • Make sure Ruby is on the PATH.
  2. Install Jekyll for Linux/Unix or Windows. This is normally performed by typing gem install jekyll, and may take a minute or two because lots of stuff is downloaded from the internet.
  3. Install Rouge highlighter by typing gem install rouge on the command line. Rouge is the highlighter required by GitHub at this time.
  4. Install wdm for auto-regeneration (gem install wdm) and Jemojis (gem install jemoji)
  5. Clone the Checkstyle Addons repo: git clone https://github.com/checkstyle-addons/checkstyle-addons.git
  6. cd checkstyle-addons
  7. git checkout gh-pages
  8. jekyll serve --watch --incremental

Now you can browse the website at http://localhost:4000

Resources

A quick list of development resources:

Quality Matters

While Checkstyle Addons tries to be as open as possible for new ideas and new code, it is also focused on quality. Thus, there are a small number of criteria that new code must meet:

People rely on Checkstyle Addons to work as documented, so it is most important to minimize bugs and have good documentation. The idea is to provide a stable and correct tool, so fixing known bugs if and when they arise has the highest priority (more than new features).