Project

Defines general information about the project.

Legend:

  • required

  • optional

  • may use environment variable

  • accepts Name Templates

  • YAML

  • TOML

  • JSON

  • Maven

  • Gradle

# 
project:
  # The name of the project.
  # May define a `JRELEASER_PROJECT_NAME` environment variable instead.
  # If undefined, defaults to the Git repository name.
  #  
  name: app

  # The version to be released.
  # May define a `JRELEASER_PROJECT_VERSION` environment variable instead.
  #  
  version: 1.0.0

  # The strategy used to parse the project version
  # May define a `JRELEASER_PROJECT_VERSION_PATTERN` environment variable instead.
  # Valid values are [`SEMVER`, `CALVER:<format>`, `JAVA_RUNTIME`, `JAVA_MODULE`, `CUSTOM`].
  # Defaults to `SEMVER`.
  #  
  versionPattern: SEMVER

  # 
  snapshot:
    # A regex to determine if the project version is snapshot
    # May define a `JRELEASER_PROJECT_SNAPSHOT_PATTERN` environment variable instead.
    #  
    pattern: .*-SNAPSHOT

    # The value of the snapshot tag.
    # May define a `JRELEASER_PROJECT_SNAPSHOT_LABEL` environment variable instead.
    # If undefined, will use `early-access`.
    #   
    label: early-access

    # Generate full changelog since last non-snapshot release.
    # May define a `JRELEASER_PROJECT_SNAPSHOT_FULL_CHANGELOG` environment variable instead.
    # Default is `false`.
    #  
    fullChangelog: true

  # A short description (60 chars max).
  #  Only if configured distributions or announcers.
  description: My awesome app

  # A more thorough explanation of the project's capabilities.
  # May use markdown syntax.
  # If left unspecified, will use the value of `description`.
  #  Only if configured distributions or announcers.
  longDescription: |
    My Awesome app is the bees knees

  # The project's website.
  #  Only if configured distributions or announcers.
  website: https://acme.com/app

  # A list of author names.
  #  Only if configured distributions or announcers.
  authors:
    - Duke

  # A list of tags.
  # 
  tags:
    - cli
    - awesome

  # The project's license.
  # It's recommended to use a valid SPDX identifier if the project is Open Source.
  # See https://spdx.org/licenses.
  #  Only if configured distributions or announcers.
  license: Apache-2.0

  # URL to the project's license.
  # 
  licenseUrl: https://spdx.org/licenses/Apache-2.0.html

  # The project's copyright notice.
  # You may set `${project.extraProperties.inceptionYear}` and `${project.authors}` instead.
  # 
  copyright: 2021 Duke

  # The project's vendor.
  # Default is empty.
  # 
  vendor: Acme inc.

  # The project's documentation site.
  # Defaults to `${project.website}`.
  # 
  docsUrl: https://acme.com/app/docs

  # Additional properties used when evaluating templates.
  #  
  extraProperties:
    # Key will be capitalized and prefixed with `project`, i.e, `projectFoo`.
    foo: bar

  # Required if there are configured distributions.
  # 
  java:
    # Maven coordinates: groupId.
    # Inherited by distributions if they do not define a value for it.
    # 
    groupId: com.acme

    # Maven coordinates: artifactId.
    # If undefined, will use ${project.name}.
    # Inherited by distributions if they do not define a value for it.
    # 
    artifactId: app

    # The minimum Java version required by consumers to run the application.
    # 
    version: 8

    # The application's entry point.
    # 
    mainClass: com.acme.Main

    # Identifies the project as being member of a multi-project build.
    # Defaults to `false`.
    # 
    multiProject: false

    # Additional properties used when evaluating templates.
    # 
    extraProperties:
      # Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
      foo: bar
# 
[project]
  # The name of the project.
  # May define a `JRELEASER_PROJECT_NAME` environment variable instead.
  #  
  name = "app"

  # The version to be released.
  # May define a `JRELEASER_PROJECT_VERSION` environment variable instead.
  #  
  version = "1.0.0"

  # The strategy used to parse the project version
  # May define a `JRELEASER_PROJECT_VERSION_PATTERN` environment variable instead.
  # Valid values are [`SEMVER`, `CALVER:<format>`, `JAVA_RUNTIME`, `JAVA_MODULE`, `CUSTOM`].
  # Defaults to `SEMVER`.
  #  
  versionPattern = "SEMVER"

  # A regex to determine if the project version is snapshot
  # May define a `JRELEASER_PROJECT_SNAPSHOT_PATTERN` environment variable instead.
  #  
  snapshot.pattern = ".*-SNAPSHOT"

  # Generate full changelog since last non-snapshot release.
  # May define a `JRELEASER_PROJECT_SNAPSHOT_FULL_CHANGELOG` environment variable instead.
  # Default is `false`.
  #  
  snapshot.fullChangelog = true

  # The value of the snapshot tag.
  # May define a `JRELEASER_PROJECT_SNAPSHOT_LABEL` environment variable instead.
  # If undefined, will use `early-access`.
  #   
  snapshot.label = "early-access"

  # A short description (60 chars max).
  #  Only if configured distributions or announcers.
  description = "My awesome app"

  # A more thorough explanation of the project's capabilities.
  # May use markdown syntax.
  # If left unspecified, will use the value of `description`.
  #  Only if configured distributions or announcers.
  longDescription = """
    My Awesome app is the bees knees
  """

  # The project's website.
  #  Only if configured distributions or announcers.
  website = "https://acme.com/app"

  # A list of author names.
  #  Only if configured distributions or announcers.
  authors = ["Duke"]

  # A list of tags.
  # 
  tags = ["cli", "awesome"]

  # The project's license.
  # It's recommended to use a valid SPDX identifier if the project is Open Source.
  # See https://spdx.org/licenses.
  #  Only if configured distributions or announcers.
  license = "Apache-2.0"

  # URL to the project's license.
  # 
  licenseUrl = "https://spdx.org/licenses/Apache-2.0.html"

  # The project's copyright notice.
  # You may set `${project.extraProperties.inceptionYear}` and `${project.authors}` instead.
  # 
  copyright = "2021 Duke"

  # The project's vendor.
  # Default is empty.
  # 
  vendor = "Acme inc."

  # The project's documentation site.
  # Defaults to `${project.website}`.
  # 
  docsUrl = "https://acme.com/app/docs"

  # Additional properties used when evaluating templates.
  #  
  extraProperties.foo = "bar"
  # Key will be capitalized and prefixed with `project`, i.e, `projectFoo`.

  # Required if there are configured distributions.

  # Maven coordinates: groupId.
  # Inherited by distributions if they do not define a value for it.
  # 
  java.groupId = "com.acme"

  # Maven coordinates: artifactId.
  # If undefined, will use ${project.name}.
  # Inherited by distributions if they do not define a value for it.
  # 
  java.artifactId = "app"

  # The minimum Java version required by consumers to run the application.
  # 
  java.version = "8"

  # The application's entry point.
  # 
  java.mainClass = "com.acme.Main"

  # Identifies the project as being member of a multi-project build.
  # Defaults to `false`.
  # 
  java.multiProject = false

  # Additional properties used when evaluating templates.
  # 
  java.extraProperties.foo = "bar"
  # Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
{
  // 
  "project": {
    // May define a `JRELEASER_PROJECT_NAME` environment variable instead.
    //  
    "name": "app",

    // The version to be released.
    // May define a `JRELEASER_PROJECT_VERSION` environment variable instead.
    //  
    "version": "1.0.0",

    // The strategy used to parse the project version
    // May define a `JRELEASER_PROJECT_VERSION_PATTERN` environment variable instead.
    // Valid values are [`SEMVER`, `CALVER:<format>`, `JAVA_RUNTIME`, `JAVA_MODULE`, `CUSTOM`].
    // Defaults to `SEMVER`.
    //  
    "versionPattern": "SEMVER",

    // 
    "snapshot": {
      // A regex to determine if the project version is snapshot
      // May define a `JRELEASER_PROJECT_SNAPSHOT_PATTERN` environment variable instead.
      //  
      "pattern": ".*-SNAPSHOT",

      // The value of the snapshot tag.
      // May define a `JRELEASER_PROJECT_SNAPSHOT_LABEL` environment variable instead.
      // If undefined, will use `early-access`.
      //   
      "label": "early-access",

      // Generate full changelog since last non-snapshot release.
      // May define a `JRELEASER_PROJECT_SNAPSHOT_FULL_CHANGELOG` environment variable instead.
      // Default is `false`.
      //  
      "fullChangelog": true
    },

    // A short description (60 chars max).
    //  Only if configured distributions or announcers.
    "description": "My awesome app",

    // A more thorough explanation of the project's capabilities.
    // May use markdown syntax.
    // If left unspecified, will use the value of `description`.
    //  Only if configured distributions or announcers.
    "longDescription": "My Awesome app is the bees knees",

    // The project's website.
    //  Only if configured distributions or announcers.
    "website": "https://acme.com/app",

    // A list of author names.
    //  Only if configured distributions or announcers.
    "authors": [
      "Duke"
    ],

    // A list of tags.
    // 
    "tags": [
      "cli",
      "awesome"
    ],

    // The project's license.
    // It's recommended to use a valid SPDX identifier if the project is Open Source.
    // See https://spdx.org/licenses.
    //  Only if configured distributions or announcers.
    "license": "Apache-2.0",

    // URL to the project's license.
    // 
    "licenseUrl": "https://spdx.org/licenses/Apache-2.0.html",

    // The project's copyright notice.
    // You may set `${project.extraProperties.inceptionYear}` and `${project.authors}` instead.
    // 
    "copyright": "2021 Duke",

    // The project's vendor.
    // Default is empty.
    // 
    "vendor": "Acme inc.",

    // The project's documentation site.
    // Defaults to `${project.website}`.
    // 
    "docsUrl": "https://acme.com/app/docs",

    // Additional properties used when evaluating templates.
    //  
    "extraProperties": {
      // Key will be capitalized and prefixed with `project`, i.e, `projectFoo`.
      "foo": "bar"
    },

    // Required if there are configured distributions.
    // 
    "java": {
      // Maven coordinates: groupId.
      // Inherited by distributions if they do not define a value for it.
      // 
      "groupId": "com.acme",

      // Maven coordinates: artifactId.
      // If undefined, will use ${project.name}.
      // Inherited by distributions if they do not define a value for it.
      // 
      "artifactId": "app",

      // The minimum Java version required by consumers to run the application.
      // 
      "version": "8",

      // The application's entry point.
      // 
      "mainClass": "com.acme.Main",

      // Identifies the project as being member of a multi-project build.
      // Defaults to `false`.
      // 
      "multiProject": false,

      // Additional properties used when evaluating templates.
      // 
      "extraProperties": {
        // Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
        "foo": "bar"
      }
    }
  }
}
<jreleaser>
  <!--
    
  -->
  <project>
    <!--
      May define a `JRELEASER_PROJECT_NAME` environment variable instead.
       
    -->
    <name>app</name>

    <!--
      The version to be released.
      If undefined, will use ${project.version} from Maven.
      May define a `JRELEASER_PROJECT_VERSION` environment variable instead.
       
    -->
    <version>1.0.0</version>

    <!--
      The strategy used to parse the project version
      May define a `JRELEASER_PROJECT_VERSION_PATTERN` environment variable instead.
      Valid values are [`SEMVER`, `CALVER:<format>`, `JAVA_RUNTIME`, `JAVA_MODULE`, `CUSTOM`].
      Defaults to `SEMVER`.
       
    -->
    <versionPattern>SEMVER</versionPattern>

    <!--
      
    -->
    <snapshot>
      <!--
        A regex to determine if the project version is snapshot
        May define a `JRELEASER_PROJECT_SNAPSHOT_PATTERN` environment variable instead.
         
      -->
      <pattern>.*-SNAPSHOT</pattern>

      <!--
        The value of the snapshot tag.
        May define a `JRELEASER_PROJECT_SNAPSHOT_LABEL` environment variable instead.
        If undefined, will use `early-access`.
          
      -->
      <label>early-access</label>

      <!--
        Generate full changelog since last non-snapshot release.
        May define a `JRELEASER_PROJECT_SNAPSHOT_FULL_CHANGELOG` environment variable instead.
        Default is `false`.
         
      -->
      <fullChangelog>true</fullChangelog>
    </snapshot>

    <!--
      A short description (60 chars max).
      If undefined, will use ${project.description} from Maven.
       Only if configured distributions or announcers.
    -->
    <description>My awesome app</description>

    <!--
      A more thorough explanation of the project's capabilities.
      May use markdown syntax.
      If left unspecified, will use the value of `description`.
       Only if configured distributions or announcers.
    -->
    <longDescription>
      My Awesome app is the bees knees
    </longDescription>

    <!--
      The project's website.
      If undefined, will use ${project.url} from Maven.
       Only if configured distributions or announcers.
    -->
    <website>https://acme.com/app</website>

    <!--
      A list of author names.
      If undefined, will use ${project.developers} from Maven, looking for
      matches of <role>author</role>
       Only if configured distributions or announcers.
    -->
    <authors>
      <author>Duke</author>
    </authors>

    <!--
      A list of tags.
      
    -->
    <tags>
      <tag>cli</tag>
      <tag>awesome</tag>
    </tags>

    <!--
      The project's license.
      If undefined, will use ${project.licenses} from Maven.
      It's recommended to use a valid SPDX identifier if the project is Open Source.
      See https://spdx.org/licenses.
       Only if configured distributions or announcers.
    -->
    <license>Apache-2.0</license>

    <!--
      URL to the project's license.
      
    -->
    <licenseUrl>https://spdx.org/licenses/Apache-2.0.html</licenseUrl>

    <!--
      The project's copyright notice.
      You may set `${project.extraProperties.inceptionYear}` and `${project.authors}` instead.
      
    -->
    <copyright>2021 Duke</copyright>

    <!--
      The project's vendor.
      Default is empty.
      
    -->
    <vendor>Acme inc.</vendor>

    <!--
      The project's documentation site.
      Defaults to `${project.website}`.
      
    -->
    <docsUrl>https://acme.com/app/docs</docsUrl>

    <!--
      Additional properties used when evaluating templates.
       
    -->
    <extraProperties>
      <!--
        Key will be capitalized and prefixed with `project`, i.e, `projectFoo`.
      -->
      <foo>bar</foo>
    </extraProperties>

    <!--
      Required if there are configured distributions.
      
    -->
    <java>
      <!--
        Maven coordinates: groupId.
        Inherited by distributions if they do not define a value for it.
        If undefined, will use ${project.groupId} from Maven.
        
      -->
      <groupId>com.acme</groupId>

      <!--
        Maven coordinates: artifactId.
        Inherited by distributions if they do not define a value for it.
        If undefined, will use ${project.artifactId} from Maven.
        
      -->
      <artifactId>app</artifactId>

      <!--
        The minimum Java version required by consumers to run the application.
        If undefined, will determined by reading the following Maven properties:
         - maven.compiler.release
         - maven.compiler.target
         - maven.compiler.source
         - project.compilerRelease
         - System.getProperty("java.version")
        
      -->
      <version>8</version>

      <!--
        The application's entry point.
        
      -->
      <mainClass>com.acme.Main</mainClass>

      <!--
        Identifies the project as being member of a multi-project build.
        Defaults to `false`.
        
      -->
      <multiProject>false</multiProject>

      <!--
        Additional properties used when evaluating templates.
        
      -->
      <extraProperties>
        <!--
          Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
        -->
        <foo>bar</foo>
      </extraProperties>
    </java>
  </project>
</jreleaser>
jreleaser {
  project {
    // May define a `JRELEASER_PROJECT_NAME` environment variable instead.
    //  
    name = 'app'

    // The version to be released.
    //  If undefined, will use ${project.version} from Gradle.
    // May define a `JRELEASER_PROJECT_VERSION` environment variable instead.
    //  
    version = '1.0.0'

    // The strategy used to parse the project version
    // May define a `JRELEASER_PROJECT_VERSION_PATTERN` environment variable instead.
    // Valid values are [`SEMVER`, `CALVER:<format>`, `JAVA_RUNTIME`, `JAVA_MODULE`, `CUSTOM`].
    // Defaults to `SEMVER`.
    //  
    versionPattern = 'SEMVER'

    // 
    snapshot {
      // A regex to determine if the project version is snapshot
      // May define a `JRELEASER_PROJECT_SNAPSHOT_PATTERN` environment variable instead.
      //  
      pattern = '.*-SNAPSHOT'

      // The value of the snapshot tag.
      // May define a `JRELEASER_PROJECT_SNAPSHOT_LABEL` environment variable instead.
      // If undefined, will use `early-access`.
      //   
      label = 'early-access'

      // Generate full changelog since last non-snapshot release.
      // May define a `JRELEASER_PROJECT_SNAPSHOT_FULL_CHANGELOG` environment variable instead.
      // Default is `false`.
      //  
      fullChangelog = true
    }

    // A short description (60 chars max).
    //  Only if configured distributions or announcers.
    description = 'My awesome app'

    // A more thorough explanation of the project's capabilities.
    // May use markdown syntax.
    // If left unspecified, will use the value of `description`.
    //  Only if configured distributions or announcers.
    longDescription = 'My Awesome app is the bees knees'

    // The project's website.
    //  Only if configured distributions or announcers.
    website = 'https://acme.com/app'

    // A list of author names.
    //  Only if configured distributions or announcers.
    authors = ['Duke']

    // A list of tags.
    // 
    tags = ['cli', 'awesome']

    // The project's license.
    // It's recommended to use a valid SPDX identifier if the project is Open Source.
    // See https://spdx.org/licenses.
    //  Only if configured distributions or announcers.
    license = 'Apache-2.0'

    // URL to the project's license.
    // 
    licenseUrl = 'https://spdx.org/licenses/Apache-2.0.html'

    // The project's copyright notice.
    // You may set `${project.extraProperties.inceptionYear}` and `${project.authors}` instead.
    // 
    copyright = '2021 Duke'

    // The project's vendor.
    // Default is empty.
    // 
    vendor = 'Acme inc.'

    // The project's documentation site.
    // Defaults to `${project.website}`.
    // 
    docsUrl = 'https://acme.com/app/docs'

    // Additional properties used when evaluating templates.
    // Key will be capitalized and prefixed with `project`, i.e, `projectFoo`.
    //  
    extraProperties.put('foo', 'bar')

    // Required if there are configured distributions.
    // 
    java {
      // Maven coordinates: groupId.
      // Inherited by distributions if they do not define a value for it.
      // If undefined, will use ${project.group} from Gradle.
      // 
      groupId = 'com.acme'

      // Maven coordinates: artifactId.
      // Inherited by distributions if they do not define a value for it.
      // If undefined, will use ${project.name} from Gradle.
      // 
      artifactId = 'app'

      // The minimum Java version required by consumers to run the application.
      // If undefined, will determined by reading the following Gradle properties:
      //  - project.targetCompatibility
      //  - project.compilerRelease
      //  - JavaVersion.current()
      // 
      version = '8'

      // The application's entry point.
      // 
      mainClass = 'com.acme.Main'

      // Identifies the project as being member of a multi-project build.
      // Defaults to `false`.
      // If undefined, will be determine based on the Gradle setup.
      // 
      multiProject = false

      // Additional properties used when evaluating templates.
      // Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
      // 
      extraProperties.put('foo', 'bar')
    }
  }
}

Version

It is assumed that the project’s version follows the Semantic Versioning specification, however not everyone is happy with this specification nor is able to follow it to the letter. Fortunately JReleaser does not impose a version format and lets you decide among the following options:

SEMVER

The version number complies with the Semantic Versioning specification. Examples:

  • 1.2.3

  • 1.2.3.TAG

  • 1.2.3+BUILD

  • 1.2.3.TAG+BUILD

The following relaxed patterns are also supported:

  • 1.2.TAG

  • 1.2+BUILD

  • 1.2.TAG+BUILD

  • 1.TAG

  • 1+BUILD

  • 1.TAG+BUILD

CALVER

The version number complies with the CalVer syntax, resulting in the following supported formats:

Tokens
  • for year:

    • YYYY: [2-9][0-9]{3}

    • YY: [1-9]|[1-9][0-9]|[1-9][0-9]{2}

    • 0Y: 0[1-9]|[1-9][0-9]|[1-9][0-9]{2}

  • for month:

    • MM: [1-9]|1[0-2]

    • 0M: 0[1-9]|1[0-2]

  • for day:

    • DD: [1-9]|[1-2][0-9]|3[0-1]

    • 0D: 0[1-9]|[1-2][0-9]|3[0-1]

  • for week:

    • WW: [1-9]|[1-4][0-9]|5[0-2]

    • 0W: 0[1-9]|[1-4][0-9]|5[0-2]

  • for MINOR: 0|[1-9]\d*

  • for MICRO: 0|[1-9]\d*

  • for MODIFIER: [a-zA-Z-][0-9a-zA-Z-]*

Restrictions
  • Format must begin with a year token.

  • If month is present so can day, but not week.

  • If week is present then neither month nor day are allowed.

  • minor must be present before micro.

  • modifier always goes at the end.

  • separator chars may be any of ., _, -.

Table 1. Examples
Pattern Version

CALVER:YYYY

2021

CALVER:YY

21

CALVER:0Y

06

CALVER:YYYY.MM

2021.1

CALVER:YYYY.0M

2021.01

CALVER:YYYY.MM.DD

2021.1.1

CALVER:YYYY.MM.0D

2021.1.01

CALVER:YYYY.WW

2021.1

CALVER:YYYY.0W

2021.01

CALVER:YYYY.MINOR.MICRO

2021.1.2

CALVER:YYYY.MM.DD_MICRO

2021.1.2_3

CALVER:YYYY.MODIFIER

2021.ALPHA1

CALVER:YYYY.MINOR.MICRO.MODIFIER

2021.1.2.ALPHA1

CALVER:YYYY.MODIFIER

2021.FOO-BAR

JAVA_RUNTIME

The version number complies with the Java Runtime Version syntax, resulting in the following supported formats:

  • 1.2.3

  • 1.2.3-PRE

  • 1.2.3+123

  • 1.2.3-PRE-OPT

  • 1.2.3+123-OPT

  • 1.2.3-PRE+456

  • 1.2.3-PRE+456-OPT

  • 1.2.3+-OPT

JAVA_MODULE

The version number complies with the Java Module Version syntax, resulting in the following supported formats:

  • 1.2.3

  • 1.2.3-PRE

  • 1.2.3+123

  • 1.2.3-PRE+456

CUSTOM

Use your own format, no pattern is enforced nor validated. Be aware that changelog generation may not be accurate as tags will be compared using their natural literal comparator, thus comparing "1" vs. "11" vs. "1.0" may not yield the expected result as these strings will not be parsed into numeric tokens.