Merge pull request #35 from Siouan/1.1

Releasing version 1.1.2

.travis.yml

@@ -1,25 +1,57 @@
-language: java
-install: true
-
-jdk:
-  - oraclejdk8
-
-before_cache:
-  - rm -f  $HOME/.gradle/caches/modules-2/modules-2.lock
-  - rm -fr $HOME/.gradle/caches/*/plugin-resolution/
-
-cache:
-  directories:
-    - $HOME/.gradle/caches/
-    - $HOME/.gradle/wrapper/
-    - $HOME/.sonar/cache
-
-addons:
-  sonarcloud:
-    organization: siouan
-    token:
-      secure: "GFJCds9c7LcfVZE82Tz9t7F6bsPGDIX8KtDAC2m+mUzUWst8fVDvTBJ7bqGGWAMN6bc+Uot5WI5wGW15e87j1z3RtLkglVpoBgsyIrFLQY69BpjByGvw4010EU0ulEHsT93YjUEyugMxBV6zdsuqsP8vZCMMkl0oI+i3Lj1YlTabMKFWw3QyQlkpIoQo3C7c5puJSDTh0dBxtd7w1lvPEtZLXxqe7B8mUvqyDfMLFmU8bHIVMvrmlxsUvXD8qkCJQJy3XIr+XW8tGc9pIad9C2t8eUj9OE87yqp87eOGoQdbdFp98/GKaqBe+4rVRZFXkjfhM3ayLCDwTiWBYVoGCB0MlNz7WdGD+pUWTaYMD59yhFjSLnEM3+XBb0jqeviZEMCRH14/cDhXA74h6n+/cjzIks3pEIFpFnvK6XQVXTHA6poPvfnfylbD8dpiS51Vpf9LWvVf1fmRb0M7L3WO3Ar/QFydAL2mDF/ibSuYbvZAQ3xVLz+5XTg0QkJnGItfKxI+W/3tkVahgqXVh6BGFzCwB5kTgMjgZ6eij25i3f7N9W4j4wBxIsQXc9JEqP0ZBBafSASmC4cHUyOrTOfYfeEqDeOZA6exeVRdLPiwLL1gjjzq5ru6Ii90oCzBQHeSeOhYOvUQl9gMXduzX5cpSqHCGFpMYynmrDmsz1D94Sk="
-
-script:
-  - ./gradlew build jacocoTestReport --scan -s
-  - sonar-scanner
+matrix:
+  include:
+    - os: linux
+      dist: trusty
+      jdk: oraclejdk8
+      script:
+        - ./gradlew check jacocoTestReport --scan
+        - sonar-scanner
+    - os: linux
+      dist: xenial
+      jdk: openjdk8
+    - os: osx
+      osx_image: xcode9.4
+      jdk: oraclejdk11
+
+matrix:
+  include:
+    - os: linux
+      dist: xenial
+      jdk: openjdk8
+      script:
+        - ./gradlew check jacocoTestReport --scan
+        - sonar-scanner
+    - os: linux
+      dist: trusty
+      jdk: oraclejdk8
+    - os: osx
+      osx_image: xcode9.4
+      jdk: oraclejdk11
+
+language: java
+
+jdk:
+  - oraclejdk8
+
+before_cache:
+  - rm -f  $HOME/.gradle/caches/modules-2/modules-2.lock
+  - rm -fr $HOME/.gradle/caches/*/plugin-resolution/
+
+cache:
+  directories:
+    - $HOME/.gradle/caches/
+    - $HOME/.gradle/wrapper/
+    - $HOME/.sonar/cache
+
+git:
+  depth: 3
+
+addons:
+  sonarcloud:
+    organization: siouan
+    token:
+      secure: "GFJCds9c7LcfVZE82Tz9t7F6bsPGDIX8KtDAC2m+mUzUWst8fVDvTBJ7bqGGWAMN6bc+Uot5WI5wGW15e87j1z3RtLkglVpoBgsyIrFLQY69BpjByGvw4010EU0ulEHsT93YjUEyugMxBV6zdsuqsP8vZCMMkl0oI+i3Lj1YlTabMKFWw3QyQlkpIoQo3C7c5puJSDTh0dBxtd7w1lvPEtZLXxqe7B8mUvqyDfMLFmU8bHIVMvrmlxsUvXD8qkCJQJy3XIr+XW8tGc9pIad9C2t8eUj9OE87yqp87eOGoQdbdFp98/GKaqBe+4rVRZFXkjfhM3ayLCDwTiWBYVoGCB0MlNz7WdGD+pUWTaYMD59yhFjSLnEM3+XBb0jqeviZEMCRH14/cDhXA74h6n+/cjzIks3pEIFpFnvK6XQVXTHA6poPvfnfylbD8dpiS51Vpf9LWvVf1fmRb0M7L3WO3Ar/QFydAL2mDF/ibSuYbvZAQ3xVLz+5XTg0QkJnGItfKxI+W/3tkVahgqXVh6BGFzCwB5kTgMjgZ6eij25i3f7N9W4j4wBxIsQXc9JEqP0ZBBafSASmC4cHUyOrTOfYfeEqDeOZA6exeVRdLPiwLL1gjjzq5ru6Ii90oCzBQHeSeOhYOvUQl9gMXduzX5cpSqHCGFpMYynmrDmsz1D94Sk="
+
+script:
+  - ./gradlew check jacocoTestReport --scan -s
+  - sonar-scanner

CONTRIBUTING.md

@@ -17,20 +17,22 @@ directly.
 
 - Apart from your preferred IDE, no other tools is required.
 - Use the integrated Gradle Wrapper executable `gradlew` to execute development tasks apart from an IDE.
-- It is an objective to keep the plugin independent, small. No dependencies shall be added without approbation.
-- All packages, classes, methods shall have a relevant documentation. A relevant documentation provides all information
-to identify the responsibility and behaviour of the class/method, such as developers don't have to inspect the code to
+- It is a requirement to keep the plugin independent, small. No dependencies shall be added without approbation.
+- All packages, classes, methods shall have a relevant documentation. A relevant documentation provides information to
+identify the responsibility and behaviour of the class/method, such as developers don't have to inspect the code to
 understand how to use it.
 - Prefer adding relevant documentation directly in the code instead of creating an implementation document, to guarantee
 accessibility for developers.
 - Designing automated unit tests with a good coverage for classes tightly coupled with Gradle API is not a
 trivial task, due to the design of this API. That's why all business processes in the plugin shall remain the most
 independent possible, away from this API, with an appropriate level of abstraction.
-- This separation between classes tightly coupled with Gradle API and classes containing business processes is
-implemented with 2 packages: `org.siouan.frontendgradleplugin.tasks` and `org.siouan.frontendgradleplugin.core`. 
-- Unit tests shall be written for all classes. Code coverage with unit tests shall be the highest possible, to avoid
-unknown behaviours at execution, and improve software maintainability, predictability, and reliability.
-- Functional tests shall be written for each task class. 
+- This separation between classes tightly coupled with Gradle API (inheritance) and classes containing business
+processes is implemented with 2 packages: `org.siouan.frontendgradleplugin.tasks` and
+`org.siouan.frontendgradleplugin.core`. 
+- Unit tests shall be written for each class in the `org.siouan.frontendgradleplugin.tasks` package. Code coverage with
+unit tests shall be the highest possible, to avoid unknown behaviours at execution, and improve software
+maintainability, predictability, and reliability.
+- Functional tests shall be written for each class in the `org.siouan.frontendgradleplugin.tasks` package.
 
 ### Executing functional tests from an IDE
 
@@ -52,4 +54,20 @@ gradlew pluginUnderTestMetadata
 'Fixed #<issue_number>'.
 - The automated test suite must be run and no test case must fail before any commit.
 
+### Continuous integration
+
+The project relies on [Travis CI Open Source][travis] to integrate continuously every change, pull request, in the
+repository. The configuration actually allows to build and test the plugin on the environments below:
+
+- Linux Ubuntu Xenial Xerus 16.04.6 LTS / OpenJDK 1.8.0_191 64 bits
+- Linux Ubuntu Trusty Tahr 14.04.5 LTS / OracleJDK 1.8.0_151 64 bits
+- Mac OS X 10.13 / OracleJDK 11.0.2 LTS 64 bits
+
+Ubuntu Xenial is the reference environment, used to analyze the source code with SonarCloud. By now, the plugin has been
+developed on Windows 10 Home with OracleJDK 1.8.0_202 64 bits and [JetBrains IntelliJ IDEA][intellij].
+
+*Note: continuous integration of Java projects on Windows is not supported by Travis yet.*
+
+[intellij]: <https://www.jetbrains.com/idea/> (IntelliJ IDEA)
 [issues]: <https://github.com/Siouan/frontend-gradle-plugin/issues> (Issues)
+[travis]: <https://travis-ci.org/> (Travis CI Open Source)

README.md

@@ -1,35 +1,33 @@
 # Frontend Gradle plugin
 
-[![Latest release 1.1.1](https://img.shields.io/badge/Latest%20release-1.1.1-blue.svg)](https://github.com/Siouan/frontend-gradle-plugin/releases/tag/v1.1.1)
+[![Latest release 1.1.2](https://img.shields.io/badge/Latest%20release-1.1.2-blue.svg)](https://github.com/Siouan/frontend-gradle-plugin/releases/tag/v1.1.2)
 [![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
 
-[![Build status](https://travis-ci.org/Siouan/frontend-gradle-plugin.svg?branch=master)](https://travis-ci.org/Siouan/frontend-gradle-plugin)
+[![Build status](https://travis-ci.org/Siouan/frontend-gradle-plugin.svg?branch=1.1)](https://travis-ci.org/Siouan/frontend-gradle-plugin)
 [![Quality gate status](https://sonarcloud.io/api/project_badges/measure?project=Siouan_frontend-gradle-plugin&metric=alert_status)](https://sonarcloud.io/dashboard?id=Siouan_frontend-gradle-plugin)
 [![Code coverage](https://sonarcloud.io/api/project_badges/measure?project=Siouan_frontend-gradle-plugin&metric=coverage)](https://sonarcloud.io/dashboard?id=Siouan_frontend-gradle-plugin)
 [![Reliability](https://sonarcloud.io/api/project_badges/measure?project=Siouan_frontend-gradle-plugin&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=Siouan_frontend-gradle-plugin)
 
-This plugin integrates frontend build tasks into a Gradle build. It is inspired by the
-[frontend-maven-plugin][frontend-maven-plugin].
-
-Detailed changes for each release are documented in the [release notes][release-notes]. The project uses [semantic
-versioning][semantic-versioning] for its releases.
+This plugin allows to integrate a frontend NPM/Yarn build into Gradle. It is inspired by the
+[frontend-maven-plugin][frontend-maven-plugin]. See the [quick start guide](#quick-start-guide) below to
+install/configure the plugin, and build your frontend application.
 
 ## Summary
 
-- [Requirements](#requirements)
-- [Installation](#installation)
-  - [Activation](#activation)
+- [Quick start guide](#quick-start-guide)
+  - [Requirements](#requirements)
+  - [Installation](#installation)
     - [Using Gradle DSL](#using-gradle-dsl)
     - [Using Gradle build script block](#using-gradle-build-script-block)
   - [Configuration](#configuration)
     - [DSL reference](#dsl-reference)
     - [Typical configuration with NPM](#typical-configuration-with-npm)
     - [Typical configuration with Yarn](#typical-configuration-with-yarn)
   - [Final steps](#final-steps)
-    - [Install Node/NPM/Yarn/frontend dependencies](#install-nodenpmyarnfrontend-dependencies)
+    - [Build the frontend](#build-the-frontend)
     - [Use Node/NPM/Yarn apart from Gradle](#use-nodenpmyarn-apart-from-gradle)
 - [Tasks reference](#tasks-reference)
-  - [Dependencies](#dependencies)
+  - [Task tree](#task-tree)
   - [Install Node](#install-node)
   - [Install Yarn](#install-yarn)
   - [Install frontend dependencies](#install-frontend-dependencies)
@@ -42,17 +40,20 @@ versioning][semantic-versioning] for its releases.
   - [What kind of script should I attach to the `checkFrontend` task?](#what-kind-of-script-should-i-attach-to-the-checkfrontend-task)
 - [Contributing][contributing]
 
-## Requirements
+## Quick start guide
+
+### Requirements
 
 The plugin supports:
 - [Gradle][gradle] 5.1+
 - [JDK][jdk] 8+ 64 bits
 - [Node][node] 6.2.1+
 - [Yarn][yarn] 1.0.0+
 
-## Installation
+The plugin is built and tested on Linux, Mac OS, Windows. For a full list of build environments used, see the
+[contributing notes][contributing].
 
-### Activation
+### Installation
 
 2 options are available.
 
@@ -63,7 +64,7 @@ This is the modern and recommended approach.
 ```gradle
 // build.gradle
 plugins {
-    id 'org.siouan.frontend' version '1.1.1'
+    id 'org.siouan.frontend' version '1.1.2'
 }
 ```
 
@@ -75,10 +76,10 @@ This approach is the legacy way to resolve and apply plugins.
 // build.gradle
 buildscript {
     repositories {
-        jcenter()
+        url 'https://plugins.gradle.org/m2/'
     }
     dependencies {
-        classpath 'org.siouan:frontend-gradle-plugin:1.1.1'
+        classpath 'org.siouan:frontend-gradle-plugin:1.1.2'
     }
 }
 
@@ -95,11 +96,14 @@ All settings are introduced hereafter, with default value for each property.
 // build.gradle
 frontend {
     // NODE SETTINGS
-    // Version of the distribution to download, used to build the URL to download the distribution, if not set.
+    // Node version, used to build the URL to download the corresponding distribution, if the 'nodeDistributionUrl'
+    // property is not set.
     nodeVersion = '10.15.3'
 
     // [Optional] Sets this property to force the download from a custom website. By default, this property is 'null',
     // and the plugin attempts to download the distribution compatible with the current platform from the Node website.
+    // The version of the distribution is expected to be the same as the one set in the 'nodeVersion' property, or this
+    // may lead to unexpected results.
     nodeDistributionUrl = 'https://nodejs.org/dist/vX.Y.Z/node-vX.Y.Z-win-x64.zip'
 
     // [Optional] Install directory where the distribution archive shall be exploded.
@@ -110,33 +114,33 @@ frontend {
     // be downloaded and installed by the plugin.
     yarnEnabled = false
 
-    // Yarn version, used to build the URL to download the corresponding distribution, if not set. If a custom
-    // 'yarnDistributionUrl' property is set, the version of the distribution is expected to be the same as the one set
-    // in the 'yarnVersion' property, or this may lead to unexpected results. This property is mandatory when the
-    // property 'yarnEnabled' is true.
+    // [Optional] Yarn version, used to build the URL to download the corresponding distribution, if the
+    // 'yarnDistributionUrl' property is not set. This property is mandatory when the 'yarnEnabled' property is true.
     yarnVersion = '1.15.2'
 
     // [Optional] Sets this property to force the download from a custom website. By default, this property is 'null',
     // and the plugin attempts to download the distribution compatible with the current platform from the Yarn website.
+    // The version of the distribution is expected to be the same as the one set in the 'yarnVersion' property, or this
+    // may lead to unexpected results.
     yarnDistributionUrl = 'https://github.com/yarnpkg/yarn/releases/download/vX.Y.Z/yarn-vX.Y.Z.tar.gz'
 
     // [Optional] Install directory where the distribution archive shall be exploded.
     yarnInstallDirectory = "${projectDir}/yarn"
 
     // OTHER SETTINGS
-    // Name of the NPM/Yarn scripts (see 'package.json' file) that shall be executing depending on the Gradle lifecycle
-    // task. The values below are passed as argument of the 'npm' or 'yarn' executable.
+    // Name of the NPM/Yarn scripts (see 'package.json' file) that shall be executed depending on the Gradle lifecycle
+    // task. The values below are passed as argument of the 'npm' or 'yarn' executables.
 
     // [Optional] Use this property only if frontend's compiled resources are generated out of the '${project.buildDir}'
     // directory. Default value is <null>. This property is directly used by the 'cleanFrontend' task. The task is
     // run when the Gradle built-in 'clean' task is run.
     cleanScript = 'run clean'
 
     // [Optional] Script called to build frontend's artifacts. Default value is <null>. This property is directly used
-    // by the 'assembleFrontend' task. The task also run when the Gradle built-in 'assemble' task is run.
+    // by the 'assembleFrontend' task. The task is run when the Gradle built-in 'assemble' task is run.
     assembleScript = 'run assemble'
 
-    // [Optional] Script called to run frontend's tests. Default value is <null>. This property is directly used by the
+    // [Optional] Script called to check the frontend. Default value is <null>. This property is directly used by the
     // 'checkFrontend' task. The task is run when the Gradle built-in 'check' task is run.
     checkScript = 'run check'
 }
@@ -159,8 +163,8 @@ frontend {
 ```gradle
 // build.gradle
 frontend {
-    yarnEnabled = true
     nodeVersion = '<X.Y.Z>'
+    yarnEnabled = true
     yarnVersion = '<X.Y.Z>'
     cleanScript = 'run clean'
     assembleScript = 'run assemble'
@@ -170,17 +174,19 @@ frontend {
 
 ### Final steps
 
-#### Install Node/NPM/Yarn/frontend dependencies
+#### Build the frontend
 
-Working with the frontend application requires the Node distribution, the Yarn distribution - if enabled, and 
-the frontend dependencies declared in the `package.json` file are all installed/up-to-date. If this is not the case, it
-is recommended to run the `installFrontend` task. Open a terminal, and execute the following command in the project's
-directory:
+Now that the plugin is correctly installed and configured, open a terminal, and execute the following command in the
+project's directory:
 
 ```sh
-gradlew installFrontend
+gradle build
 ```
 
+If the frontend application is part of a full-stack Java artifact, take a look at
+[this guide](#how-to-assemble-a-frontend-and-a-java-backend-in-a-single-artifact) to assemble the frontend and the
+backend together.
+
 #### Use Node/NPM/Yarn apart from Gradle
 
 If Node/NPM/Yarn may be used apart from Gradle, it is mandatory to apply the following steps:
@@ -199,9 +205,9 @@ environment variable.
 The plugin registers multiple tasks, some having dependencies with other, and also with Gradle lifecycle tasks defined
 in the [Gradle base plugin][gradle-base-plugin].
 
-### Dependencies
+### Task tree
 
-![Task dependencies][task-dependencies]
+![Task tree][task-tree]
 
 ### Install Node
 
@@ -279,7 +285,6 @@ Assembling the frontend before the backend shall not be difficult to setup in Gr
 ```sh
 gradlew taskTree --no-repeat assemble
 
-:build
 :assemble
 +--- :assembleFrontend
 |    \--- :installFrontend
@@ -324,12 +329,12 @@ tasks.named('processResources').configure {
 
 ### What kind of script should I attach to the `checkFrontend` task?
 
-The `checkFrontend` task is a dependency of the `check` task. The Gradle official documentation states that the `check`
-task shall be used to `attach [...] verification tasks, such as ones that run tests [...]`. It's enough vague to let you
-consider any verification task. The script mapped to the `checkFrontend` task may run either automated unit tests, or
-functional tests, or a linter, or any other verification action, or even combine some or all of them. Every combination
-is possible, since you can define a script in your `package.json` file that executes sequentially the actions of your
-choice.
+The `checkFrontend` task is attached to the lifecycle `check` task. The Gradle official documentation states that the
+`check` task shall be used to `attach [...] verification tasks, such as ones that run tests [...]`. It's enough vague to
+let you consider any verification task. The script mapped to the `checkFrontend` task may run either automated unit
+tests, or functional tests, or a linter, or any other verification action, or even combine some or all of them. Every
+combination is even possible, since you can define a script in your `package.json` file that executes sequentially the
+actions of your choice.
 
 [contributing]: <CONTRIBUTING.md> (Contributing to this project)
 [frontend-maven-plugin]: <https://github.com/eirslett/frontend-maven-plugin> (Frontend Maven plugin)
@@ -339,11 +344,10 @@ choice.
 [gradle-dsl]: <https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block> (Gradle DSL)
 [gradle-java-plugin]: <https://docs.gradle.org/current/userguide/java_plugin.html> (Gradle Java plugin)
 [gradle-spring-boot-plugin]: <https://docs.spring.io/spring-boot/docs/current/gradle-plugin/reference/html/> (Gradle Spring Boot plugin)
-[j2ee]: <https://www.oracle.com/technetwork/java/javaee/> (J2EE)
 [jdk]: <https://docs.oracle.com/en/java/javase/> (Java Development Kit)
 [node]: <https://nodejs.org/> (Node.js)
 [release-notes]: <https://github.com/siouan/frontend-gradle-plugin/releases> (Release notes)
 [semantic-versioning]: <https://semver.org/> (Semantic versioning)
 [spring-boot]: <https://spring.io/projects/spring-boot> (Spring Boot)
-[task-dependencies]: <task-dependencies.png>
+[task-tree]: <task-tree.png>
 [yarn]: <https://yarnpkg.com/> (Yarn)

build.gradle

@@ -19,8 +19,8 @@ repositories {
 test {
     useJUnitPlatform()
     testLogging {
+        showStandardStreams = true
         events "passed", "skipped", "failed"
-        exceptionFormat = 'full'
     }
 }
 
@@ -41,7 +41,7 @@ dependencies {
 }
 
 group 'org.siouan'
-version '1.1.1'
+version '1.1.2'
 description 'Integrate your frontend NPM/Yarn build into Gradle.'
 
 sourceCompatibility = JavaVersion.VERSION_1_8

sonar-project.properties

@@ -1,6 +1,6 @@
 sonar.projectKey=Siouan_frontend-gradle-plugin
 sonar.projectName=frontend-gradle-plugin
-sonar.projectVersion=1.1.1
+sonar.projectVersion=1.1.2
 
 sonar.links.homepage=https://github.com/Siouan/frontend-gradle-plugin
 sonar.links.ci=https://travis-ci.org/Siouan/frontend-gradle-plugin