gradle-about-plugin

This library and Gradle plugin are able to read .ABOUT files.

ABOUT file is an excellent way to describe your project - what it is, how it is licensed, is it intended for public

or for internal use only and so on.

Maven has pom.xml, which contains all this metadata. Gradle doesn’t.

In Gradle world a lot of build authors store metadata about their projects inside build script, using some plugins like nebula.contacts or org.kordamp.gradle.licensing.

The problem with this approach is that in order to get this metadata programmatically you have to run Gradle, let the project to be configured and read this configuration with some tricky script. Or to repeat yourself duplicating the same information somewhere else. Imagine that you need your CI to run specific stage IF the project is licensed under specific license. How would you accomplish that? Is your approach really efficient and DRY?

The other problem is that these Gradle plugins are mostly opinionated. There are no common practices.

Separate standardised .ABOUT file, in YAML format, is a solution. CI build can read it and know what it is building beforehand. Gradle build can read it and use the same metadata during build. Also YAML is simple enough so human users can read it too.

Extended .ABOUT format specification

TODO

Gradle plugins

TODO

.ABOUT file fields used

.ABOUT file can be used for both source code and binaries. For sources, filling some fields makes no sense.

The following table contains:

• recommendations which .ABOUT fields should be set if .ABOUT file describes source code

• usage by plugins (mappings to fields in plugins being integrated)

(prefix org.fidata.about. is skipped from plugin IDs for brevity)

.ABOUT file field	jvm.maven-publish	jvm.ivy-publish	jvm.bintray	nebula.contacts	jvm.plugin-publish
about_resource	Required. I recommend you to set it to . (single dot, meaning current directory)
description	description	descriptor.description.text			description
homepage_url	url	descriptor.description.homepage	websiteUrl		website
owner	These fields don’t differentiate organizations from persons. Use maven_organization and maven_developers fields instead
owner_url
contact
author
author_file
license_expression	I recommend to set this
licenses.*.file
licenses.*.url	licenses.*.url	descriptor.license.url
licenses.*.name	licenses.*.name	descriptor.license.name
licenses.*.key	I recommend to set this
licenses.*.maven_comments	licenses.*.comments
licenses.*.maven_distribution	licenses.*.distribution
redistribute	When SPDX-listed licenses are used then the information for these fields can (and should) be derived programmatically. In this case I don’t recommend to set them. DRY and SSOT
attribute
track_changes
maven_vcs_developer_connection_url	vcsDeveloperConnectionUrl
maven_inception_year	inceptionYear
maven_organization.name	organization.name
maven_organization.url	organization.url
maven_developers.*	developers.*
maven_contributors.*	contributors.*
maven_issue_management.system	issueManagement.system
maven_issue_management.url	issueManagement.url		issueTrackerUrl
maven_ci_management.*	ciManagement.*
maven_mailing_lists.*	mailingLists.*
extended_keywords			labels		tags

Differences with aboutcode-toolkit

aboutcode-toolkit	gradle-about-plugin	Notes/Reasoning
Handles all custom fields as StringField s	Respects suffixes described by specification for file and URL fields Allows extensibility with custom fields of complex types	Simpler extensibility Gives validation of values in custom file and url fields
Parses licenses field into 4 separate lists	Has designated License class	Simpler and bug-free architecture Determined behavior when there are several licenses
Requires some string fields to be single line	Accepts multiline strings as well	It is not mentioned in specification. We consider this as a bug in aboutcode-toolkit
Validates .ABOUT content and returns list of found errors	Just throws exception when something is not valid	Use separate Gradle plugin and task to run about check and be sure that .ABOUT file is correct
Reads contents of TextFileFields	Doesn’t read them	There was no need
Stores Field name	Doesn’t store Field name	It’s not so easy to get field name from Jackson It’s not obvious which name should be assigned to list items For our goals, there is little utility in field name
Doesn’t validate license_expression field	Validates it
Prohibits null values	Currently allows null values	Bug in Jackson FasterXML/jackson-databind#2024
Is able to read .ABOUT in Json and Csv formats as well	Is not able to read them	There was no need
Is able to save (serialize) .ABOUT	Is not able to save	There was no need
Keeps order of fields	Generally, doesn’t keep order of fields (preserves order of string, file, URL and custom non-mapped fields, but all fields mapped to separate classes are parsed to separate Java class fields, which have no 'order')	There was no need