= Project

Defines general information about the project.

include::partial$legend.adoc[]

[tabs]
====
YAML::
+
[source,yaml]
[subs="+macros"]
----
# icon:exclamation-triangle[]
project:
  # The name of the project.
  # May define a `JRELEASER_PROJECT_NAME` environment variable instead.
  # icon:exclamation-triangle[] icon:eye-slash[]
  name: app

  # The version to be released.
  # May define a `JRELEASER_PROJECT_VERSION` environment variable instead.
  # icon:exclamation-triangle[] icon:eye-slash[]
  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`, `JAVA_MODULE`, `CUSTOM`].
  # Defaults to `SEMVER`.
  # icon:dot-circle[] icon:eye-slash[]
  versionPattern: SEMVER

  # A regex to determine if the project version is snapshot
  # May define a `JRELEASER_PROJECT_SNAPSHOT_PATTERN` environment variable instead.
  # icon:dot-circle[] icon:eye-slash[]
  snapshotPattern: .*-SNAPSHOT

  # A short description (60 chars max).
  # icon:exclamation-triangle[] 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`.
  # icon:dot-circle[] Only if configured distributions or announcers.
  longDescription: |
    My Awesome app is the bees knees

  # The project's website.
  # icon:exclamation-triangle[] Only if configured distributions or announcers.
  website: pass:[https://acme.com/app]

  # A list of author names.
  # icon:exclamation-triangle[] Only if configured distributions or announcers.
  authors:
    - Duke

  # A list of tags.
  # icon:dot-circle[]
  tags:
    - cli
    - awesome

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

  # The project's copyright notice.
  # You may set `${project.extraProperties.inceptionYear}` and `${project.authors}` instead.
  # icon:dot-circle[]
  copyright: 2021 Duke

  # The project's documentation site.
  # Defaults to `${project.website}`.
  # icon:dot-circle[]
  docsUrl: pass:[https://acme.com/app/docs]

  # Additional properties used when evaluating templates.
  # icon:dot-circle[] icon:file-alt[]
  extraProperties:
    # Key will be capitalized and prefixed with `project`, i.e, `projectFoo`.
    foo: bar

  # Required if there are configured distributions.
  # icon:dot-circle[]
  java:
    # Maven coordinates: groupId.
    # Inherited by distributions if they do not define a value for it.
    # icon:exclamation-triangle[]
    groupId: com.acme

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

    # The minimum Java version required by consumers to run the application.
    # icon:exclamation-triangle[]
    version: 8

    # The application's entry point.
    # icon:dot-circle[]
    mainClass: com.acme.Main

    # Identifies the project as being member of a multi-project build.
    # Defaults to `false`.
    # icon:dot-circle[]
    multiProject: false

    # Additional properties used when evaluating templates.
    # icon:dot-circle[]
    extraProperties:
      # Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
      foo: bar
----
TOML::
+
[source,toml]
[subs="+macros"]
----
# icon:exclamation-triangle[]
[project]
  # The name of the project.
  # May define a `JRELEASER_PROJECT_NAME` environment variable instead.
  # icon:exclamation-triangle[] icon:eye-slash[]
  name = "app"

  # The version to be released.
  # May define a `JRELEASER_PROJECT_VERSION` environment variable instead.
  # icon:exclamation-triangle[] icon:eye-slash[]
  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`, `JAVA_MODULE`, `CUSTOM`].
  # Defaults to `SEMVER`.
  # icon:dot-circle[] icon:eye-slash[]
  versionPattern = "SEMVER"

  # A regex to determine if the project version is snapshot
  # May define a `JRELEASER_PROJECT_SNAPSHOT_PATTERN` environment variable instead.
  # icon:dot-circle[] icon:eye-slash[]
  snapshotPattern = ".*-SNAPSHOT"

  # A short description (60 chars max).
  # icon:exclamation-triangle[] 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`.
  # icon:dot-circle[] Only if configured distributions or announcers.
  longDescription = """
    My Awesome app is the bees knees
  """

  # The project's website.
  # icon:exclamation-triangle[] Only if configured distributions or announcers.
  website = "pass:[https://acme.com/app]"

  # A list of author names.
  # icon:exclamation-triangle[] Only if configured distributions or announcers.
  authors = ["Duke"]

  # A list of tags.
  # icon:dot-circle[]
  tags = ["cli", "awesome"]

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

  # The project's copyright notice.
  # You may set `${project.extraProperties.inceptionYear}` and `${project.authors}` instead.
  # icon:dot-circle[]
  copyright = "2021 Duke"

  # The project's documentation site.
  # Defaults to `${project.website}`.
  # icon:dot-circle[]
  docsUrl = "pass:[https://acme.com/app/docs]"

  # Additional properties used when evaluating templates.
  # icon:dot-circle[] icon:file-alt[]
  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.
  # icon:exclamation-triangle[]
  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.
  # icon:exclamation-triangle[]
  java.artifactId = "app"

  # The minimum Java version required by consumers to run the application.
  # icon:exclamation-triangle[]
  java.version = "8"

  # The application's entry point.
  # icon:dot-circle[]
  java.mainClass = "com.acme.Main"

  # Identifies the project as being member of a multi-project build.
  # Defaults to `false`.
  # icon:dot-circle[]
  java.multiProject = false

  # Additional properties used when evaluating templates.
  # icon:dot-circle[]
  java.extraProperties.foo = "bar"
  # Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
----
JSON::
+
[source,json]
[subs="+macros"]
----
{
  // icon:exclamation-triangle[]
  "project": {
    // May define a `JRELEASER_PROJECT_NAME` environment variable instead.
    // icon:exclamation-triangle[] icon:eye-slash[]
    "name": "app",

    // The version to be released.
    // May define a `JRELEASER_PROJECT_VERSION` environment variable instead.
    // icon:exclamation-triangle[] icon:eye-slash[]
    "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`, `JAVA_MODULE`, `CUSTOM`].
    // Defaults to `SEMVER`.
    // icon:dot-circle[] icon:eye-slash[]
    "versionPattern": "SEMVER",

    // A regex to determine if the project version is snapshot
    // May define a `JRELEASER_PROJECT_SNAPSHOT_PATTERN` environment variable instead.
    // icon:dot-circle[] icon:eye-slash[]
    "snapshotPattern": ".*-SNAPSHOT",

    // A short description (60 chars max).
    // icon:exclamation-triangle[] 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`.
    // icon:dot-circle[] Only if configured distributions or announcers.
    "longDescription": "My Awesome app is the bees knees",

    // The project's website.
    // icon:exclamation-triangle[] Only if configured distributions or announcers.
    "website": "pass:[https://acme.com/app]",

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

    // A list of tags.
    // icon:dot-circle[]
    "tags": [
      "cli",
      "awesome"
    ],

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

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

    // The project's documentation site.
    // Defaults to `${project.website}`.
    // icon:dot-circle[]
    "docsUrl": "pass:[https://acme.com/app/docs]",

    // Additional properties used when evaluating templates.
    // icon:dot-circle[] icon:file-alt[]
    "extraProperties": {
      // Key will be capitalized and prefixed with `project`, i.e, `projectFoo`.
      "foo": "bar"
    },

    // Required if there are configured distributions.
    // icon:dot-circle[]
    "java": {
      // Maven coordinates: groupId.
      // Inherited by distributions if they do not define a value for it.
      // icon:exclamation-triangle[]
      "groupId": "com.acme",

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

      // The minimum Java version required by consumers to run the application.
      // icon:exclamation-triangle[]
      "version": "8",

      // The application's entry point.
      // icon:dot-circle[]
      "mainClass": "com.acme.Main",

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

      // Additional properties used when evaluating templates.
      // icon:dot-circle[]
      "extraProperties": {
        // Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
        "foo": "bar"
      }
    }
  }
}
----
Maven::
+
[source,xml]
[subs="+macros,verbatim"]
----
<jreleaser>
  <!--
    icon:exclamation-triangle[]
  -->
  <project>
    <!--
      May define a `JRELEASER_PROJECT_NAME` environment variable instead.
      icon:exclamation-triangle[] icon:eye-slash[]
    -->
    <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.
      icon:exclamation-triangle[] icon:eye-slash[]
    -->
    <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`, `JAVA_MODULE`, `CUSTOM`].
      Defaults to `SEMVER`.
      icon:dot-circle[] icon:eye-slash[]
    -->
    <versionPattern>SEMVER</versionPattern>

    <!--
      A regex to determine if the project version is snapshot
      May define a `JRELEASER_PROJECT_SNAPSHOT_PATTERN` environment variable instead.
      icon:dot-circle[] icon:eye-slash[]
    -->
    <snapshotPattern>.*-SNAPSHOT</snapshotPattern>

    <!--
      A short description (60 chars max).
      If undefined, will use ${project.description} from Maven.
      icon:exclamation-triangle[] 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`.
      icon:dot-circle[] 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.
      icon:exclamation-triangle[] Only if configured distributions or announcers.
    -->
    <website>pass:[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>
      icon:exclamation-triangle[] Only if configured distributions or announcers.
    -->
    <authors>
      <author>Duke</author>
    </authors>

    <!--
      A list of tags.
      icon:dot-circle[]
    -->
    <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 link:https://spdx.org/licenses[].
      icon:exclamation-triangle[] Only if configured distributions or announcers.
    -->
    <license>Apache-2.0</license>

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

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

    <!--
      Additional properties used when evaluating templates.
      icon:dot-circle[] icon:file-alt[]
    -->
    <extraProperties>
      <!--
        Key will be capitalized and prefixed with `project`, i.e, `projectFoo`.
      -->
      <foo>bar</foo>
    </extraProperties>

    <!--
      Required if there are configured distributions.
      icon:dot-circle[]
    -->
    <java>
      <!--
        Maven coordinates: groupId.
        Inherited by distributions if they do not define a value for it.
        If undefined, will use ${project.groupId} from Maven.
        icon:dot-circle[]
      -->
      <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.
        icon:dot-circle[]
      -->
      <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")
        icon:dot-circle[]
      -->
      <version>8</version>

      <!--
        The application's entry point.
        icon:dot-circle[]
      -->
      <mainClass>com.acme.Main</mainClass>

      <!--
        Identifies the project as being member of a multi-project build.
        Defaults to `false`.
        icon:dot-circle[]
      -->
      <multiProject>false</multiProject>

      <!--
        Additional properties used when evaluating templates.
        icon:dot-circle[]
      -->
      <extraProperties>
        <!--
          Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
        -->
        <foo>bar</foo>
      </extraProperties>
    </java>  
  </project>
</jreleaser>
----
Gradle::
+
[source,groovy]
[subs="+macros"]
----
jreleaser {
  project {
    // May define a `JRELEASER_PROJECT_NAME` environment variable instead.
    // icon:exclamation-triangle[] icon:eye-slash[]
    name = 'app'

    // The version to be released.
    //  If undefined, will use ${project.version} from Gradle.
    // May define a `JRELEASER_PROJECT_VERSION` environment variable instead.
    // icon:exclamation-triangle[] icon:eye-slash[]
    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`, `JAVA_MODULE`, `CUSTOM`].
    // Defaults to `SEMVER`.
    // icon:dot-circle[] icon:eye-slash[]
    versionPattern = 'SEMVER'

    // A regex to determine if the project version is snapshot
    // May define a `JRELEASER_PROJECT_SNAPSHOT_PATTERN` environment variable instead.
    // icon:dot-circle[] icon:eye-slash[]
    snapshotPattern = '.*-SNAPSHOT'

    // A short description (60 chars max).
    // icon:exclamation-triangle[] 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`.
    // icon:dot-circle[] Only if configured distributions or announcers.
    longDescription = 'My Awesome app is the bees knees'

    // The project's website.
    // icon:exclamation-triangle[] Only if configured distributions or announcers.
    website = 'pass:[https://acme.com/app]'

    // A list of author names.
    // icon:exclamation-triangle[] Only if configured distributions or announcers.
    authors = ['Duke']

    // A list of tags.
    // icon:dot-circle[]
    tags = ['cli', 'awesome']

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

    // The project's copyright notice.
    // You may set `${project.extraProperties.inceptionYear}` and `${project.authors}` instead.
    // icon:dot-circle[]
    copyright = '2021 Duke'

    // The project's documentation site.
    // Defaults to `${project.website}`.
    // icon:dot-circle[]
    docsUrl = 'pass:[https://acme.com/app/docs]'

    // Additional properties used when evaluating templates.
    // Key will be capitalized and prefixed with `project`, i.e, `projectFoo`.
    // icon:dot-circle[] icon:file-alt[]
    extraProperties.put('foo', 'bar')

    // Required if there are configured distributions.
    // icon:dot-circle[]
    java {
      // Maven coordinates: groupId.
      // Inherited by distributions if they do not define a value for it.
      // If undefined, will use ${project.group} from Gradle.
      // icon:dot-circle[]
      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.
      // icon:dot-circle[]
      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()
      // icon:dot-circle[]
      version = '8'

      // The application's entry point.
      // icon:dot-circle[]
      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.
      // icon:dot-circle[]
      multiProject = false

      // Additional properties used when evaluating templates.
      // Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
      // icon:dot-circle[]
      extraProperties.put('foo', 'bar')
    }
  }
}
----
====

== Version

It is assumed that the project's version follows the link:https://semver.org/[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

=== JAVA_MODULE

The version number complies with the link:https://docs.oracle.com/javase/9/docs/api/java/lang/module/ModuleDescriptor.Version.html[Java Module Version]
syntax, resulting in the following supported formats:

 * 1.2.3
 * 1.2.3-PRE
 * 1.2.3+BUILD
 * 1.2.3-PRE+BUILD

=== 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.

