Setting up a new Project

Initial files

Gradle build properties

gradle.properties

(1)
version=0.0.1
(2)
group=org.ysb33r.gradle
(3)
projectStartYear=2017
(4)
projectLicenseType=Apache 2.0

1	Set the project version.
2	Set the group.
3	Set the year that the project started. If this value is not set, then `ysfProject.inceptionYear` has to be set in every project.
4	Set the project license type. If this value is not set, then `Apache 2.0` is assumed. You can also set `ysfProject.licenseType` on every project.

Create a file that defines the header that will be placed in source files. This file normally contains a {year} entry that is substituted with the copyright years.

License header file

Set up a license file and in the copyright line of the license file, put something like below.

gradle/license/HEADER

(C) Copyright ${year} Schalk W. Cronjé and/or respective authors as
     identified in documentation sections.

Also set up a file in the root of the project with the name LICENSE which is textual representation of the license.

Minimal version catalog

gradle/libs.versions.toml

[versions]
pluginYsfProject = "0.1.0"

[plugins]
ysfProjectDocs = { id = "org.ysb33r.ysf-project.docs.antora", version.ref = "pluginYsfProject" }
ysfProjectJvm = { id = "org.ysb33r.ysf-project.core.jvm", version.ref = "pluginYsfProject" }
ysfProjectGradlePlugin = { id = "org.ysb33r.ysf-project.gradle-plugin", version.ref = "pluginYsfProject" }
ysfProjectSonatype = { id = "org.ysb33r.ysf-project.sonatype.ossrh", version.ref = "pluginYsfProject" }

Build settings file

In addition to including any subproject, if you have a multi-project, AND setting the root project name, add the following to the top of the settings.gradle file.

settings.gradle

pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }
}

plugins {
    id 'org.gradle.toolchains.foojay-resolver-convention' version '0.8.0'
    id "com.gradle.develocity" version "3.18.1"
}

develocity {
    buildScan {
        termsOfUseUrl = "https://gradle.com/help/legal-terms-of-use"
        termsOfUseAgree = "yes"
        publishing.onlyIf { System.getenv('CI') != null }
    }
}

Build file(s)

If you have a single project you can do the following.

build.gradle

plugins {
  alias(libs.plugins.ysfProjectDocs)
  alias(libs.plugins.ysfProjectJvm)
  alias(libs.plugins.ysfProjectGradlePlugin) (1)
  alias(libs.plugins.ysfProjectSonatype) (2)
}

ysfProject {
  overview {
      description = 'Give the project a title' (3)
      maintainers 'ysb33r' (4)
      contributors 'someoneElse' (5)
  }
  antora {
      title = 'Gradle Plugin Suite for Internal YSF Projects' (6)
      preserveLegacyDocumentation = false (7)
  }
  asciidoc {
      discordChannel = 'ysf-project-gradle-plugin-suite' (8)
      withGradleDocAttributes() (9)
  }
  jvm {
    javaLanguageVersion = 8 (10)
    artifactDescription = 'An example of an artifact description' (11)
  }
}
repositories {
  mavenCentral()
}

1	Only required if you are building a Gradle plugin.
2	Only required if you are publishing to Sonatype’s OSSRH.
3	Give the project a title
4	List the Gitlab identifiers of the project maintainers
5	List the Gitlab identifiers of significant contributors.
6	Set the title that should be on the documentation.
7	If the project has legacy documentation that should be preserved, set this to `true`.
8	Set the name of the Discord channel for discussing this project.
9	Only needed if this project includes the construction of Gradle plugins.
10	Set the Java language version.
11	Set this when building a library.

For a multi-project you will configure it slightly different.

build.gradle

plugins {
  alias(libs.plugins.ysfProjectDocs)
  alias(libs.plugins.ysfProjectJvm) apply false
  alias(libs.plugins.ysfProjectGradlePlugin) apply false (1)
  alias(libs.plugins.ysfProjectSonatype) apply false (2)
}

ysfProject {
  overview {
      description = 'Give the project a title' (3)
  }
  antora {
      title = 'Gradle Plugin Suite for Internal YSF Projects' (4)
      preserveLegacyDocumentation = false (5)
  }
  asciidoc {
      discordChannel = 'ysf-project-gradle-plugin-suite' (6)
      withGradleDocAttributes() (7)
  }
  docs {
      projectsWithDocuments { path -> path.endsWith('-plugin')} (8)
  }
}

allprojects {
  repositories {
    mavenCentral()
  }
}

1	Only required if you are building a Gradle plugin.
2	Only required if you are publishing to Sonatype’s OSSRH.
3	Give the project a title
4	Set the title that should be on the documentation.
5	If the project has legacy documentation that should be preserved, set this to `true`.
6	Set the name of the Discord channel for discussing this project.
7	Only needed if this project includes the construction of Gradle plugins.
8	If you have subprojects which needs the API documentation to be included, add this line. The filter will be provided a project path, and it should return `true` if the subproject should be included.

my-subproject/build.gradle

plugins {
  alias(libs.plugins.ysfProjectJvm)
  alias(libs.plugins.ysfProjectGradlePlugin) (1)
  alias(libs.plugins.ysfProjectSonatype) (2)
}

ysfProject {
  jvm {
    javaLanguageVersion('11')(3)
  }
}

gradlePlugin { (4)
  plugins {
    // Define plugins
  }
}

1	Only required if this subproject produces Gradle plugins.
2	Only required if this subproject produces a library that will be published on Maven Central.
3	Set the Java language version.
4	Only needed if this subproject produces Gradle plugins. See Gradle Plugin Publish plugin for more details.

Set the JDK for running Gradle

Create a .sdkmanrc file for those people who use SDKMan! and has the setting sdkman_auto_env=true in configuration

.sdkmanrc

 # Enable auto-env through the sdkman_auto_env config
# Add key=value pairs of SDKs to use below
java=21.0.4-amzn

If you are using IntelliJ remember to go the Build Tools section and set the JDK version accordingly.

Configure .gitigore

Although projects will vary, this is a good starting point.

.gitignore

.asciidoctorconfig
.generated-src
.idea
.offline-repo
.settings
build/
.gradle/
TMP/

Antora files

Assuming that you will build documentation set up the following layout.

antora.yml
display-versions.txt
nav.adoc
index.adoc

A minimalistic antora.yml file.

docs/antora.yml

name: "##COMPONENT##"
title: "##TITLE##"
version: "##VERSION##"
start_page: "##STARTDOC##"
nav:
  - modules/ROOT/nav.adoc
asciidoc:
  attributes:
    revnumber: "##VERSION##"

A file which lists the versions that needs to be included in documentation It should at minimum contain the current version.

docs/display-versions.txt

# These are versions that were listed when we build documentation the old landinge page way.
#
0.0.0.1

A basic navigation file.

docs/modules/ROOT/nav.adoc

* xref:index.adoc[Overview]

Also add the docs/modules/ROOT/pages/index.adoc. You probably want to include this section in your index.adoc file.

docs/modules/ROOT/pages/index.adoc

.Support this project
****
image:https://img.icons8.com/color/48/patreon.png[Patreon,48,48] If you like this project, consider donating to our https://www.patreon.com/bePatron?u=55368021[Patreon account].
****

image:https://img.icons8.com/color/48/discord-new-logo.png[Discord,48,48] We are on Discord. link:{discord-join-link}[Click to join] and then go to `#{discord-project-channel}`.

image:https://img.icons8.com/external-tal-revivo-shadow-tal-revivo/48/external-mastodon-is-an-online-self-hosted-social-media-and-social-networking-service-logo-shadow-tal-revivo.png[Mastodon,48,48] Follow us https://fosstodon.org/ysb33rOrg[`@ysb33rOrg@fosstodon.org`] in the `#Fediverse`

image:https://img.icons8.com/color/48/gitlab.png[Gitlab,48,48] link:{gitlab-project-url}[Fork this project on Gitlab]

Changelog

If you plan to maintain a manual changelog, place a CHANGELOG.adoc file in the root of the project.

CHANGELOG.adoc

= Changelog

== 0.0.1  (1)
// tag::changelog[] (2)

=== Features

=== Bugs

=== Other

=== Breaking changes

// end::changelog[]

1	You’ll need a version
2	As new versions get released this `tag` delimiter and the corresponding end `end` delimiter will be moved around as to only include details for the current version.

You should then add a symbolic link in the docs/modules/ROOT/partials directory back to CHANGELOG.adoc

$ pushd docs/modules/ROOT/partials
$ ln -s ../../../../CHANGELOG.adoc
$ popd

Now create a changelog.adoc file in docs.modules/ROOT/pages directory.

docs/modules/ROOT/pages/changelog.adoc

= Release notes

include::partial$CHANGELOG.adoc[tags=changelog,leveloffset=-1]

Finally, update docs/modules/ROOT/nav.adoc and append the following

docs/modules/ROOT/nav.adoc

.Changelog
* xref:changelog.adoc[Release notes]

Developers list

You also need to define the list of contributors and maintainers. The build will fail, if this file does not exist.

It is a Yaml file and it has two sections being maintainers & contributors.

gradle/developers.yml

maintainers:
  - name: Schalk W. Cronjé
    email: yw-github@af.org.za
    gitlab: ysb33r

contributors:
  - name: John Doe

Setup pipeline

.gitlab-ci.yml

include:
  - component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/pipeline-publish-artifacts-and-docs@VERSION_TAG (1)
    inputs:
      jdk: 21 (2)
  - component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@VERSION_TAG (3)
    inputs:
      versions: 7.6.1 (4)
  - component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@VERSION_TAG
    inputs:
      versions: 8.6,8.7,8.9

1	Replace `VERSION_TAG` with the pipeline version you want to lock the pipeline to. There is a list of version tags.
2	Set the version of the JDK that Gradle must run with.
3	If the project produces one of more Gradle plugins, add one or more of these entries to parition compatibility testing. For more details on configuring `GradleTest` in the pipeline see GradleTest in CI.
4	Lists the versions that needs to be tested in a job.

For more details see on how pipelines work and for more configuration settings, see the pipeline recipe README.