gradle-base-plugins

Plugins to configure Gradle to build projects (including other Gradle pluging) developed by FIDATA. They provide reasonable defaults and sane environment for all our projects.

These plugins are highly opinionated and for internal use only. They are not to be published to Maven Central or Gradle Plugins portal. However, you are free to fork, modify or use it as an example according to LGPL v3.0+ license.

If you are contributing to other FIDATA plugins the best choice is to join FIDATA organization and use all available infrastructure including our Artifactory repository where these plugins live.

org.fidata.project plugin

General, language-agnostic project.

Lifecycle

Basic build lifecycle is assemble → check → release.

assemble, check and, also, clean tasks are provided by applied lifecycle-base plugin.

release task is provided by applied de.gliderpilot.semantic-release plugin.

Prerequisites Lifecycle

• Applies org.fidata.prerequisites providing tasks for dealing with prerequisites managed by Gradle, Bundler, NPM and similar tools.

  To report outdated Gradle dependencies com.github.ben-manes.versions plugin is used.

• Configures wrapper task to specific Gradle version

Dependency Resolution

• Adds Maven repository hosted on FIDATA Artifactory

  For releases, it is always -release repository, so releases cannot have snapshot dependencies. Otherwise it is -snapshot repository, so snapshot versions could be used during development (but won't by default - see below).

• Turns off changing modules caching, so that SNAPSHOT dependencies are updated on each run

• Configures dependency resolution changing Ivy status from release to milestone for artifacts having pre-release labels in version

• Adds property status to each ExternalModuleDependency instance. It should be used to configure desired status of dependency. By default all dependencies are resolved to releases, even if you use version ranges. If you want to get bleeding edge SNAPSHOT version you could use this property, like this:

  dependencies {
    compile('com.example:next-generation-library:[1, 2[').status = 'integration'
  }

  Of course, if there is more recent release with appropriate version then it will be used instead of old SNAPSHOT.

  Custom status schemes are not supported.

Documentation

• Applies and configures org.ajoberstar.git-publish plugin

  Allows to publish documentation to GitHub pages.

• Provides noJekyll task that generates .nojekyll file to turn off Jekyll processing

Code Quality

• Provides lint task

  check task depends on all Test tasks and new lint task.

• Applies codenarc plugin

• Provides codenarc and pmd tasks that run all PMD and CodeNarc tasks respectively.

  Includes these tasks in execution list for lint task.

• Provides codenarcBuildSrc task for build.gradle itself and accompanying Groovy scripts

• Sets default configuration for all codenarc tasks

  Adds disabledRules property to each task, so that specific rules could be disabled per task.

Artifacts Publishing

• Applies signing plugin

  By default, Java-based implementation of PGP is used. Secret keyring should be placed at GnuPG home in secring.gpg file.

  If you want to use GnuPG for signing, properties for this are already set. Switch can be made with signing.useGpgCmd() .

• Provides read-only isRelease and changeLog project properties for working with semantic release

• Provides publicReleases project property used by other plugins

  Setting it to true turns on all public-release tasks: publishing artifacts to Maven Central, JCenter and so on.

  By default it is false.

Reports

• Provides read-only project properties:

  • reportsDir
  • htmlReportsDir
  • xmlReportsDir
  • jsonReportsDir
  • txtReportsDir

• Applies and configures reporting-base plugin

  Redirects all reports to build/reports/<format> directory.

  Known limitation: gradle --profile reports are not redirected. They stay in build/reports/profile directory for now. See https://github.com/FIDATA/gradle-base-plugins/issues/1

Build Diagnostics and Troubleshooting

• Applies plugins:

  • project-report

    Provides projectReport and other tasks.

  • com.dorongold.task-tree

    Provides taskTree task. It is wonderful in troubleshooting task dependencies.

• Provides inputsOutputs task which generates reports about all task file inputs and outputs

All these tasks are put into Diagnostics group.

Other features

• Applies and configures com.jfrog.artifactory plugin

  Allows us to publish artifacts and build info to FIDATA Artifactory .

• Sets project's group to org.fidata if it hasn't been set already

• Provides license property used by other plugins

  It should be set with SPDX license identifier .

• Provides generateChangelog and generateChangelogTxt tasks that generate changelog in Markdown and text formats in build/changelog directory

  The main usage is to check generated changelog during release preparation to make sure that everything is correct.

• Provides tags property used by other plugins

• Applies nebula.contacts plugin

  Provides contacts extension.

Git Workflow

Earlier in the history we tried to use GitFlow. But it didn't work out well. GitHub doesn't support fast-forward merges. So, there was a big mess each time we merged from develop to master. Also, this led to unnecessary rebuilds on Jenkins.

Our current workflow resembles GitHub workflow and OneFlow.

• We make all development in feature/… and hotfix/… branches, and maybe branches with some other prefixes

• All work is merged to master via PRs with merge commits

• master should be release-able any time. But actual releases are manually triggered. Gradle's release task will make a release only when shouldRelease project property is passed and set to true. This could be done from command line, like ./gradlew release -PshouldRelease=true, of manually via parameter of Jenkins build.

• We don't have develop branch with the same purpose as in GitFlow. But we can use develop branch for general/various improvements when there is no unique feature or hotfix to describe changes. In this case we merge PR with rebase merging

• We don't use release branches and don't support several major/minor releases simultaneously

buildSrc projects

Plugin can be applied to buildSrc projects. However, buildSrc projects can't have releases and documentation, so all related features are turned off. They also don't publish build info to Artifactory.

They could have code quality and diagnostic tasks, but usage of them is discouraged. Note that all buildSrc's Gradle and Groovy scripts are already covered by codenarcBuildSrc task.

Project gets isBuildSrc read-only property which will be set to true when buildSrc project is detected.

Supported tools versions:

• Requires Gradle >= 5.1

• Built and tested with JDK 8

• Requires GnuPG >= 2.1

  gpg-agent should have allow-preset-passphrase option turned on if GPG key with passphrase is used. It is usually achieved by adding this string into gpg-agent.conf file in GPG home directory.

  gpg-preset-passphrase should be available in the path.

org.fidata.base.jvm plugin

Project which uses JVM-based language. This plugin should not be applied manually.

Applies org.fidata.project plugin, and also:

• Applies java-base and java-library plugins

• Provides jvm extension. This extension has one property javadocLinks.

  It contains links to external documentation used by javadoc and groovydoc. If a dependency is added automatically, its documentation is also added here automatically. Otherwise, you add link manually, like this:

  jvm.javadocLinks['com.example.super.cool.external.library'] = uri('https://example.com/javadoc/com/example/super.cool.external.library/1.0/')

• Adds mavenJava publication (except when org.fidata.plugin is applied)

Testing

• Adds JUnit dependency to testImplementation configuration

• Adds and configures functionalTest source set and task which uses Spock framework

  Also adds Spock Reports.

  JUnit is also available whenever Spock is.

Artifact Publishing

• Applies maven-publish plugin

  Configures Maven publication to Artifactory.

  If publicReleases is on — configures publication to Maven Central.

• If publicReleases is on — applies com.jfrog.bintray plugin and configures publication to JCenter

Code Quality

• Provides findbugs and jdepend tasks that run all FindBugs and JDepend tasks respectively.

  Includes these tasks in execution list for lint task.

Other features

• Adds license file(s) into JAR META-INF directory

org.fidata.project.java plugin

Java language project.

Applies org.fidata.base.jvm plugin, and also:

• Applies java plugin

• Applies io.franzbecker.gradle-lombok plugin providing Lombok for Java sources

• Configures javadoc to parse sources through Delombok first

• Adds javadoc output to GitHub Pages publication

• Provides checkstyle task that run all Checkstyle tasks.

  Includes this task in execution list for lint task.

org.fidata.base.groovy plugin

Project which uses Groovy language. This plugin should not be applied manually.

Applies org.fidata.base.jvm plugin, and also:

• Applies groovy-base plugin

org.fidata.project.groovy plugin

Groovy language project.

Applies org.fidata.base.groovy plugin, and also:

• Applies groovy plugin

• Adds local Groovy to api configuration

• Adds groovydoc output to GitHub Pages publication

org.fidata.plugin plugin

Gradle plugin project.

This plugin depends on at least one of JVM-based project plugins:

• org.fidata.project.java
• org.fidata.project.groovy

or others developed later.

They have to be applied manually depending on the language(s) used in the project.

• Applies java-gradle-plugin plugin

• Configures groovydoc links to Gradle API

• Adds Gradle TestKit dependency to functionalTest source set configurations

• Applies org.ysb33r.gradletest and org.ajoberstar.stutter plugins

  Provides and configures gradleTest and compatTest source sets. Allows us to test plugins under several different Gradle versions.

• If publicReleases is on — applies com.gradle.plugin-publish plugin

  pluginBundle.plugins should be configured manually. Other properties are set automatically.

• Sets project's group to org.fidata.gradle if it hasn't been set already

Properties

Should be provided in standard Gradle ways .

All properties except gpgKeyPassphrase are required. The plugin won't work if they are not set.

Multi-project Builds (a.k.a Monorepo)

These plugins supports multi-project builds in the following configuration:

1. All child projects have the same version as the root one. This is the limitation imposed by de.gliderpilot.semantic-release plugin.

2. org.fidata.project should be applied to root. It applies itself to each subproject

3. de.gliderpilot.semantic-release and org.ajoberstar.git-publish plugins are applied to root only.

4. The following properties are available for root project only:

   • isBuildSrc
   • isRelease
   • changeLog
   • changeLogTxt
   • issuesUrl
   • vcsUrl

   Except these, all other is configurable per project.

   Note that subprojects can have different licenses, and license file(s) (being included in JARs) are per project.

5. Reports for all subprojects are redirected to build/reports/<format>/<subproject> directory. This is made for convenient usage under CI (Jenkins)

Development

This is self-applying plugin. That means that build script requires the plugin itself (just compiled, not released to the repository). So, if there are any errors during compilation or plugin applying, Gradle build script just doesn't work. If it is a compilation error, you can run ../gradlew build in buildSrc directory to figure out what's going on.

Upgrading Gradle Version

Whenever new Gradle version is released, the way to upgrade is this:

1. Read Release Notes and make necessary changes to the code
2. Run ./gradlew stutterWriteLock
3. Run ./gradlew compatTest<new Gradle version>
4. Change Gradle version for wrapper task in plugin code
5. Run ./gradlew wrapper && ./gradlew wrapper

If a new version of a plugin won't be compatible with previous Gradle versions:

1. Update ProjectPlugin.GRADLE_MINIMUM_SUPPORTED_VERSION value
2. Run ./gradlew stutterWriteLock
3. Update required Gradle version in this README file

Copyright © Basil Peace

This file is part of gradle-base-plugins.

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.