Gradle Github info plugin

Additional

Language
Groovy
Version
1.1.0 (Apr 7, 2016)
Created
Dec 5, 2015
Updated
Mar 28, 2018
Owner
Vyacheslav Rusakov (xvik)
Contributor
Vyacheslav Rusakov (xvik)
1
Activity
Badge
Generate
Download
Source code

Show card

Gradle Github info plugin

About

Plugin generates common github links (like repository, issues, vcs etc) for project and configures common plugins. The main intention is to remove boilerplate and simplify project configuration.

  • Add github configuration closure. In most cases requires only user and license to apply conventions.
  • github may be used directly in other configuration closures (e.g. github.site)
  • Configures default values for maven-publish (pom), plugin-publish and com.jfrog.bintray plugins

You can use it with java-lib plugin to remove more configuration boilerplate for java or groovy library.

Setup

Releases are published to bintray jcenter, maven central and gradle plugins portal.

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'ru.vyarus:gradle-github-info-plugin:1.1.0'
    }
}
apply plugin: 'ru.vyarus.github-info'

OR

plugins {
    id 'ru.vyarus.github-info' version '1.1.0'
}

Usage

Minimum required configuration:

github {
    user 'test'
    license 'MIT'    
}

User may be used to define either user or organization (links will be correct for both). github.repository will be set to project name by default.

Other license properties may be also required (see below).

All other properties are generated by conventions. You can override any property.

If some required properties are not set validation error will be thrown to prevent incorrect usage.

Using in configurations

All properties may be used in other configurations

github {
    user 'test'
    license 'MIT'
}

somePlugin {
    websiteUrl github.site
    vcsUrl github.vcsUrl
    importantFileUrl github.rawFileUrl('IFile.txt')
}

Available properties

Property Description Default value
user Github user or organization name
repository Github repository name $project.name
license License short name (e.g. 'MIT')
licenseName License full name (e.g. 'The MIT License') may be set by convention (see license section)
licenseUrl Url to license file may be set by convention (see license section)
repositoryUrl Github repository url https://github.com/$user/$repository
issues Url to github issues https://github.com/$user/$repository/issues
site Project website $repositoryUrl
vcsUrl Version control url https://github.com/$user/${repository}.git
scmConnection SCM connection url scm:git:git://github.com/$user/${repository}.git
changelogFile Path to changelog file, relative to project root CHANGELOG.md, CHANGELOG.txt or CHANGELOG if file found in project root

License

Plugin contains hardcoded info for most common licenses:

License ID License name
Apache Apache License 2.0
GPLv2 GNU General Public License 2.0
GPLv3 GNU General Public License 3.0
AGPL GNU Affero General Public License 3.0
LGPLv2.1 The GNU Lesser General Public License 2.1
LGPLv3 The GNU Lesser General Public License 3.0
MIT The MIT License
Artistic Artistic License 2.0
EPL Eclipse Public License 1.0
BSD 3-clause The BSD 3-Clause License
MPL Mozilla Public License 2.0

If license property value is one of license id above then licenseName will be set. Otherwise, licenseName must be specified manually.

licenseUrl default:

  • Looks if LICENSE or LICENSE.txt file contained in project root, then url will be https://raw.githubusercontent.com/$user/$repository/master/LICENSE (or with txt extension accordingly)
  • If license file not found in project, but license matches known license id (table above) then url will be set as link to opensource.org (see links above)
  • If neither license file found nor license id recognized then url must be set manually

Utility method

github.rawFileUrl(file, branch) method may be used in build script to generate direct (raw) urls to files on github repository.

For example,

github.rawFileUrl('folder/file.txt')

Will generate the following url:

https://raw.githubusercontent.com/$user/$repository/master/folder/file.txt

Branch parameter is optional ('master' by default)

Plugins defaults

Plugin recognize some common plugins and apply default values to them (but not overrides user configuration!)

maven-publish

If maven-publish plugin available, then for all defined publications pom will be extended with:

<url>${github.site}</url>
<scm>
    <url>${github.vcsUrl}</url>
    <connection>${github.scmConnection}</connection>
    <developerConnection>${github.scmConnection}</developerConnection>
</scm>
<licenses>
    <license>
        <name>${github.licenseName}</name>
        <url>%{github.licenseUrl}</url>
        <distribution>repo</distribution>
    </license>
</licenses>
<issueManagement>
    <system>GitHub</system>
    <url>${github.issues}</url>
</issueManagement>

plugin-publish

If publish-plugin plugin available, then following defaults will be applied:

pluginBundle {
    website = github.site
    vcsUrl = github.vcsUrl
}

So you can avoid these properties in pluginBundle configuration in your build file. If you manually specify any of these values it will not be overridden.

com.jfrog.bintray

If com.jfrog.bintray plugin available, then following defaults will be applied:

bintray {
    pkg {
        websiteUrl = github.site
        issueTrackerUrl = github.issues
        vcsUrl = github.vcsUrl
        licenses = [github.license]
        githubRepo = "$github.user/$github.repository"
        githubReleaseNotesFile = github.changelogFile
    }
}

So you can avoid these properties in bintray configuration in your build file. If you manually specify any of these values it will not be overridden.

Note that github* properties are required to configure bintray ui for showing github readme as main documentation and changelog as release notes files

Might also like