Grails 3 plugins are distributed through Bintray. This is great because it provides everyone the ability to easily publish their own plugins. Bintray is a generic distribution platform and might be a bit overwhelming at first, but it’s a great platform for distribution and it’s also quickly becoming the new de-facto standard for Jars as opposed to Maven Central. There are a couple items that newcomers might get stuck on though when publishing their first Grails 3 plugin and this post will hopefully help those users get started.

If you don’t have a Bintray account, go create one! It’s free and really easy. Also, if you haven’t read this blog post, please read it and come back when done. It provides a good introduction.

Now that you have an account and maybe have published a simple plugin, it’s time to hopefully answer a few questions you might have encountered!

1) Where is the Group ID on the Bintray artifact page?

Maven artifacts are represented as groupId:artifactId:version. The artifactId and version are easy to find in Bintray, but not the groupId. To find the groupId, you have to go to the file, and click on (i) icon to see the maven/gradle dependency snippet. By default, all Grails plugins use the groupId of org.grails.plugins, but you can certainly change this if you’d like. There is no hard requirement to use this groupId for your plugin. The groupId is set in build.gradle like this: group 'org.grails.plugins'

2) I see some Grails plugins named “org.grails.plugins:something” and some named just “something”. What is the correct Bintray package naming standard for a Grails plugin?

Name it just the short name or the equivalent of the artifactId (something). Do not put org.grails.plugins or any other groupId in the Bintray package name. The convention of groupId:artifactId is from when Maven artifacts were migrated to Bintray and should not be used for new packages. Your Maven repository artifacts in Bintray still have a groupId regardless of what you name the package. I updated the sample publishing artifacts (more details below in #6) to accommodate this recommendation in this commit.

3) How do I find the actual project for a Bintray package?

I don’t have a good answer for this question, but rather what I will say is that given Bintray is a completely separate binary management system from Grails, we as a community need to be a little more diligent about ensuring we have correct meta-data for our plugins so community members don’t have to dig for information. For instance, always provide these data elements in gradle.settings for your plugin:

websiteUrl = 'https://somebody.github.io/grails-something'
issueTrackerUrl = 'https://github.com/somebody/grails-something/issues'
vcsUrl = 'https://github.com/somebody/grails-something'

I’m recommending the GitHub Pages URL for a repo (the gh-pages branch) to always be the website for your plugin since there is no longer a “Grails plugin portal page” for Grails 3 plugins. I would recommend using AsciiDoc to build any new documentation as opposed to the Grails documentation engine. You can see a good example of AsciiDoc being used for plugin documentation here. These URLs will then show up on the Bintray package page and make it easy for users to find the source.

4) How do I change the name of my plugin?

I like the convention of starting Grails plugin GitHub repos with grails- in the name. By default, Gradle takes the name of the root folder as the artifactId though. So, that would make the artifact called grails-something which obviously isn’t what we want. We want our plugin to be published as something. This is easy to fix though by creating a settings.gradle file in the root of our plugin repo with one attribute rootProject.name = "something".

5) What does “linking” my package mean and how do I get my plugin to be listed as a “Grails 3 plugin”?

Every Bintray user has their own repositories and your packages will be published to one of them. To use these binaries, you need to add your repository to your build file for dependency resolution (i.e. places to look for dependencies). Linking simply means add my package to another repository other than the one I published it to. For example, there is a big repository in Bintray called jcenter that you can link your artifacts with so that other users don’t have add your repository since a lot of people already have jcenter listed as a repository in their build file. Well, we have the same concept with the Grails Plugins repository. By linking your Grails plugin with that repository, users will not have to add your repository to find it and it will show up as a Grails 3 plugin! This is certainly not required, but it will be much easier for other community members to find and use your plugin if you link it with the Grails Plugins repository.

6) What are these “apply from: https://raw.githubusercontent.com/grails/grails-profile-repository/…” lines in my plugin build file?

Those two lines simply include bintray and publishing sections in your build file and can be considered a guide for how to configure these settings. These are actually going away for Grails 3.1+ though as there will be a new plugin for helping with publishing. You can see in this commit that I applied the same recommendation from #2 for naming Bintray packages to be just the artifactId.

7) What is the “grails-plugin” attribute in Bintray publishing?

That grails-plugin attribute is simply meta-data to query Bintray to find packages. Attributes can be added to repositories, packages and versions. In the future, if there is a separate plugin portal we can leverage the grails-plugin attribute to quickly find plugins in Bintray. Obviously having your plugin(s) added to the Grails Plugins repository in Bintray accomplishes the same thing though.

I hope you found this post helpful in answering some questions about publishing Grails 3 plugins. Thanks for reading!