Setting up a new Project
Initial files
Gradle build 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.
(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
[versions]
pluginYsfProject = "0.0.8"
[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.
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.
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.
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. |
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
# 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.
.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.
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.
# These are versions that were listed when we build documentation the old landinge page way.
#
0.0.0.1
A basic navigation file.
* 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.
.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
== 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.
= Release notes
include::partial$CHANGELOG.adoc[tags=changelog,leveloffset=-1]
Finally, update docs/modules/ROOT/nav.adoc
and append the following
.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
.
maintainers:
- name: Schalk W. Cronjé
email: yw-github@af.org.za
gitlab: ysb33r
contributors:
- name: John Doe
Setup pipeline
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.