Skip to content

Latest commit

 

History

History
93 lines (53 loc) · 3.88 KB

CONTRIBUTING.md

File metadata and controls

93 lines (53 loc) · 3.88 KB
Raw

Contributing Code or Documentation to the Micronaut Framework

Finding Issues to Work on

If you are interested in contributing to the Micronaut Framework and are looking for issues to work on, take a look at the issues tagged with help wanted.

JDK Setup

The Micronaut Framework currently requires JDK 17

IDE Setup

The Micronaut Framework project is imported into IntelliJ IDEA by opening the build.gradle file.

Docker Setup

The Micronaut Framework tests require Docker.

Running Tests

To run the tests use ./gradlew check.

Geb functional tests are ignored unless you specify the geb environment via system property.

To run with Chrome ./gradlew -Dgeb.env=chrome check.

To run with Firefox ./gradlew -Dgeb.env=firefox check.

Building Documentation

The documentation sources are located at src/main/docs/guide.

To build the documentation run ./gradlew publishGuide or ./gradlew pG then open build/working/02-docs-raw/index.html

This only generates the raw guide without the API and Configuration references; therefore, the API links in the manual will not resolve in a browser.

To include the API (javadocs) and Configuration references run ./gradlew docs instead and open build/docs/index.html

Working on the code base

If you are working with the IntelliJ IDEA development environment, you can import the project using Intellij's Gradle Tooling ("File / Open..." and select the "build.gradle" file or the project directory).

Create a branch from the release branch to which you anticipate merging back changes, e.g. 3.4.x, 3.5.x, 3.6.x, etc.

The most important task to complete before submitting work is the check task. This executes all the unit tests as well as various code quality checks.

./gradlew check

The check task should complete successfully. Otherwise, the initial pull request will fail, and you will need to make corrections before it can be reviewed (unless you are opening a draft pull request).

Creating a pull request

Once you are satisfied with your changes:

  • Commit changes to the local branch you created.
  • Push that branch with changes to the corresponding remote branch on GitHub
  • Submit a pull request

Checkstyle

The code base should remain clean, following industry best practices for organization, javadoc and style, as much as possible.

The Micronaut Framework uses Checkstyle to make sure that all the code follows those standards. The configuration file is defined in config/checkstyle/checkstyle.xml. To execute the Checkstyle task run:

./gradlew <module-name>:checkstyleMain

Before contributing new code it is recommended you install IntelliJ CheckStyle-IDEA plugin and configure it to use Micronaut Framework's checkstyle configuration file.

IntelliJ will mark in red the issues Checkstyle finds. For example:

checkstyle-issue

In this case, to fix the issues, we need to:

  • Add one empty line before package in line 16
  • Add the Javadoc for the constructor in line 27
  • Add a space after if in line 34

The plugin also adds a new tab in IDEA's bottom view pane to run a checkstyle report to display errors and warnings. Run the report and fix any exposed issues before submitting a pull request. The gradle check task also produces an HTML report if there are errors.

Building on Windows 10

The following prerequisites are needed for building and testing on Windows 10:

  • Docker Desktop version 2.0.0.0 win81 build 29211 or higher is installed and running.
  • OpenSSL's binaries are installed, for example (https://indy.fulgan.com/SSL/) and on the PATH.