Gradle plugin yeoman generator

About

Generates gradle plugin project configured to publish to plugins portal and (optionally) to jcenter (and maven central). Project assumes hosting on github.

Features:

• MIT license (hardcoded)
• Plugin sample
• Tests samples with ProjectBuilder and TestKit
• Configured for publishing to plugins portal and maven central
• CI: github actions (linux), appveyor (windows)
• Coverage with jacoco, merged from both win and linux builds in codecov.io
• Code quality checks with CodeNarc
• Release process (like maven release)

Note: gradle 6.9 used instead of 7.x because groovy plugin compiled under 7.x would not be compatible with the previous gradle versions (plugin would be usable only with gradle 7.x, which is not desired)

Known issue

Gradle 2.13+ has a bug with console input. As a result, during release version confirm questions are not visible.

Issue is not blocking and only affects release process: simply hit enter for questions (and be sure version in properties file is correct).

Example projects

• gradle-quality-plugin
• gradle-mkdocs-plugin
• gradle-use-python-plugin
• gradle-pom-plugin
• gradle-java-lib-plugin
• gradle-github-info-plugin
• gradle-animalsniffer-plugin

Important

Gradle propose publishing plugins to plugins portal, but some users prefer using plugins only from maven central (for security reasons), so it is a good idea to publish into both.

By default, when plugin published to plugins portal, its group is prefixed with 'gradle.plugin' (so if your group was 'com.foo', real artifact group will be 'gradle.plugin.com.foo'). Such default behaviour grants immediate plugin publishing. If you want to mirror plugin on maven central it's better to force your group name. In this case plugin will require manual approve before it appears on portal (it should be approved within 1 day, but in my case it was two weeks). After approve you can publish new plugins with the same group without approve (the same as in maven central).

Generator supports all possible options (based on your answers):

• publish to plugins portal only with default group (portal will prepend 'gradle.plugin' to your group)
• publish to plugins portal only with forced group (requires approve)
• publish to plugins portal with forced group and to jcenter (optionally to maven central)

Note: plugin-publish plugin use its own tasks to prepare published artifacts. In order to upload to maven central project will use different tasks (defined by java-lib plugin). So artifacts published to plugin portal and maven central will be different (jars content will be almost identical, but they will be build by different tasks).

NOTE: you can also publish plugins into local repository (e.g. internal nexus), but you'll have to manually modify generated project (generate with maven central publication) - read below.

Setup

Install yeoman:

$ npm install -g yo

Install generator:

$ npm install -g generator-gradle-plugin

Github setup

You will need github user. Create it if you don't have already.

Gradle user

You will need gradle user to upload to plugins portal.

In your profile page go to API keys tab and generate api key. Add key and secret to ~/.gradle/gradle.properties

gradle.publish.key=
gradle.publish.secret=

Maven central setup

For maven central publication you must first register in sonatype and approve your group. Read this a bit outdated article for getting started.

For certificate generation see java-lib plugin docs Note that signing configuration required only for release (otherwise its ignored)

After all you'll need to put the following properties into ~/.gradle/gradle.properties

sonatypeUser =
sonatypePassword =

signing.keyId = 78065050
signing.password =
signing.secretKeyRingFile = /path/to/certs.gpg

Generator will check and warn you if something is not configured.

Publishing plugin to local repository only

If plugin is assumed to be used as internal plugin with local (corporate) maven repo, manual modifications required.

Generate project for maven central publication.

Remove com.gradle.plugin-publish (no need to publish to portal) and io.github.gradle-nexus.publish-plugin.

Remove ru.vyarus.github-info (I assume your source would not be in github). And remove related github configuration block.

Remove signing plugin if you don't need to sign artifacts for your repository.

Configure repository:

publishing {
    repositories {
        maven {
            url project.version.contains("SNAPSHOT")
                    ? "https://my-private-nexus.com/nexus/content/repositories/my-snapshots"
                    : "https://my-private-nexus.com/nexus/content/repositories/my-releases"
            credentials {
                username = project.findProperty('myRepoUser')
                password = project.findProperty('myRepoPass')
            }
        }
    }
}

Disable gradle-plugin publication (normally used for portal publication):

tasks.withType(AbstractPublishToMaven) { Task task ->
    if (task.name.startsWith("publishPluginMaven")) {
        task.enabled(false)
    }
}

NOTE: there is still an additional publication used: gradle would publish marker artifact required for plugins syntax.

Change releasing task:

afterReleaseBuild {
    dependsOn = [publish]

Now simple publish task deploys snapshot version and release task would perform complete release (with version change and tagging git).

To use plugins from custom repo add to settings.gradle (in project requiring published plugin):

pluginManagement {
    repositories {
        maven {
            // usually root repo combining releases and snapshots
            url 'https://my-private-nexus.com/nexus/content/groups/my/'
        }
        gradlePluginPortal()
    }
}

With it plugin from custom repo could be enabled in plugins section the same way as plugin from gradle portal (thanks to additionally published marker artifact).

Usage

General convention: project name == github project name

Run generator:

$ yo gradle-plugin

Generator creates project in current folder if project name (question) is the same as current directory, and will create subdirectory otherwise.

Generator calls github to validate user correctness and suggest your name and email. If there is a problem with it use offline mode:

$ yo gradle-plugin --offline

Project setup ready, start coding!

Build upgrade

If you preserve .yo-rc.json file (your answers) in generated project root you will be able to use update mode.

Run generator project directory:

$ cd my-project
$ yo gradle-plugin 

Generator will work in update mode: it will use answers stored in .yo-rc.json and re-generate project files. It will not generate sample sources again and also will not touch: CHANGELOG.md, README.md, gradle.properties, LICENSE and settings.gradle.

It updates:

• Project gradle (wrapper files, scripts and version in build.gradle)
• Gradle configs: build.gradle, settings.gradle
• gitignore

This mode is useful when project isn't changed much after generation. In case when you have multiple projects it greatly simplifies projects upgrade: doing all changes manually could lead to forgotten changes, but with generator its impossible to forget something because all changes are always done.

Start update without local changes and after generation look git changes and correct (usually only main build.gradle requires modifications after update).

Global storage

Most likely, some answers will be the same for all your plugins, that's why they are stored in global config and you will see more precise defaults on next generation.

Global config stored in ~/.config/configstore/generator-gradle-plugin.json

External services

Create github repo matching your plugin name and push project there (github will guide you).

In github project settings go to Webhooks & services and add travis-ci service.

Enable repository on appveyor

And after next commit windows and linux builds will be performed automatically and combined coverage report will be available on codecov (badges for all services are already generated in readme).

Maven central and gradle portal badges are generated in readme.

Project usage

$ gradlew check

Runs code quality plugins. If quality checks were activated (asked during generation) do check before pushing to avoid build failures on travis. Moreover, it's easy to always keep everything clean instead of doing it before release.

$ gradlew dependencyUpdates

Checks if your project dependencies are actual and prints versions analysis report to console.

$ gradlew dependencies

Prints dependencies tree into console

$ gradlew openDependencyReport

Generates dependencies html report and launch it in default browser. To analyze conflicts, click on dependency name to activate dependencyInsight popup.

$ gradlew install

Installs plugin to local maven repository. Useful for referencing by other projects (for testing without releasing plugin).

NOTE: gradle will complain about multiple publications with the same coordinates - that's fine (install publish all publications - one prepared for central and another used by gradle portal publication)

For example, to use not released but installed to local maven in gradle project:

buildscript {
    repositories { mavenLocal() }
    classpath 'group:artifact:version-SNAPSHOT'
}
apply plugin: 'my.plugin'

(or just puty snapshot version in plugins section if settings.gradle contains mavenLocal for plugins resolution)

$ gradlew release

Releases plugin. Read release process section below before performing first release.

Project details

Note that gradle api dependencies are not specified directly, but project will implicitly have localGroovy(), gradleApi() and gradleTestKit() dependencies applied by java-gradle-plugin

Used gradle plugins:

• groovy as main used language
• jacoco for coverage recording
• java-gradle-plugin assist plugin development
• com.gradle.plugin-publish to publish to gradle plugins portal
• maven-publish to generate pom and publish to maven repository
• project-report to generate dependency tree html report
• codenarc to check quality with CodeNarc
• o.github.gradle-nexus.publish-plugin to simplify maven central publication
• com.github.ben-manes.versions to check dependencies versions updates
• net.researchgate.release for release (see article for additional plugin details)
• ru.vyarus.pom for simpler pom generation
• ru.vyarus.java-lib to prepare java artifacts setup
• ru.vyarus.github-info to fill in github specific data
• ru.vyarus.quality to configure codenarc plugin and provide advanced reporting
• pl.droidsonroids.jacoco.testkit to spport coverage recordings in testkit based tests

Quality

CodeNarc quality plugin is configured by ru.vyarus.quality plugin.

Read more about plugin specifics and how to suppress warnings

By default, quality checks fail build if any violation found. In order to simply report violations do:

quality {
    strict = false
}

Testing

Generator will genarate sample plugin and two types of tests:

• With ProjectBuilder
• Using TestKit

Project build tests are good for checking configuration. They run in the same vm and so they are fast.

TestKit tests are useful to validate tasks execution (especially if there are files operations involved). These tests use real gradle build run. TestKit tests may be launched even for different gradle versions.

For more tests examples see my plugins sources.

NOTE: if tests failed to run in your IDE, then run tests from gradle first (tests task). Gradle generates classpath file before running TestKit tests (tests can't work without this file). When tests run from IDE, file generation is not triggered automatically, so have to keep in mind this workaround.

Release process

Before first release

When releasing first time it's better to do

$ gradlew install

And validate generated pom file and jars (in local maven repository ~/.m2/repository/..).

General release process

Update CHANGELOG.md.

Push all changes before release and wait for travis to check build (wait for green badge).

Perform release:

$ gradlew release

Release will check that current copy is actual: no uncommitted/unversioned/unpushed changes, nothing newer is in remote repository. You can start releasing either from snapshot version (1.0.0-SNAPSHOT) or from normal one (1.0.0).

During release, plugin will create tag (new github release appear) and update version in gradle.properties.

You may want to create github release: release will only create tag. To create release go to github releases, click on tag and press 'edit'. I usually use text from changelog as release message, but you may expand it with other release specific notes.