Add quick start pages

2026-03-10 08:31:25 +00:00 · 2021-03-28 01:20:09 +01:00
parent 9c1dd7a983
commit a23af9a9d1
8 changed files with 569 additions and 4 deletions
--- a/docs/antora.yml
+++ b/docs/antora.yml
@@ -7,6 +7,7 @@ asciidoc:
    icons: font
 nav:
 - modules/ROOT/nav-start.adoc
+- modules/quick-start/nav.adoc
 - modules/configuration/nav.adoc
 - modules/tools/nav.adoc
 - modules/ROOT/nav-end.adoc
--- a/docs/modules/ROOT/nav-start.adoc
+++ b/docs/modules/ROOT/nav-start.adoc
@@ -1,2 +1 @@
 * xref:install.adoc[]
-* xref:quick_start.adoc[]
--- a/docs/modules/configuration/pages/project.adoc
+++ b/docs/modules/configuration/pages/project.adoc
@@ -317,7 +317,7 @@ jreleaser {
    name = 'app'

    // The version to be released.
-      If undefined, will use ${project.version} from Gradle.
+    //  If undefined, will use ${project.version} from Gradle.
    // May define a `JRELEASER_PROJECT_VERSION` environment variable instead.
    // [required]
    version = '1.0.0'
--- a/docs/modules/quick-start/nav.adoc
+++ b/docs/modules/quick-start/nav.adoc
@@ -0,0 +1,5 @@
+.Quick Start
+* xref:quick-start-cli.adoc[]
+* xref:quick-start-maven.adoc[]
+* xref:quick-start-gradle.adoc[]
+* xref:quick-start-ant.adoc[]
--- a/docs/modules/quick-start/pages/quick-start-ant.adoc
+++ b/docs/modules/quick-start/pages/quick-start-ant.adoc
@@ -0,0 +1,102 @@
+= Quick Start - Ant
+
+Yiur Ant build must be configured to create binary distributions (Zips and Tars). Review the
+link:http://ant.apache.org/[Ant] documentation to find out how to do that. Follow the instructions
+in the xref:ROOT:install.adoc[] section to download and install the JReleaser Ant tasks. Once configured
+you an bootstrap a configuration file
+
+[source]
+----
+$ ant jreleaser-init -Djreleaser.format=yml
+Buildfile: /Home/duke/app/build.xml
+
+jreleaser-init:
+Writing file /Home/duke/app/jreleaser.yml
+JReleaser initialized at /Home/duke/app
+
+BUILD SUCCESSFUL
+Total time: 0 seconds
+----
+
+This generates a `jreleaser.yml` file with the following configuration
+
+[source,yaml]
+.jreleaser.yml
+----
+project:
+  name: app
+  version: 1.0.0-SNAPSHOT
+  description: Awesome App
+  longDescription: Awesome App
+  website: https://acme.com/app
+  authors:
+    - Duke
+  license: Apache-2
+  java:
+    groupId: com.acme
+    version: 8
+
+release:
+  github:
+    owner: duke
+
+distributions:
+  app:
+    artifacts:
+      - path: path/to/{{distributionName}}-{{projectVersion}}.zip
+----
+
+Edit the file to suite your needs. JReleaser *does not* create artifact files for you. It assumes those are created using
+Ant; JReleaser only cares if the resolved artifact paths exist. Once you have edited the file you may verify its
+configuration by invoking
+
+[source]
+----
+$ ant jreleaser-config
+----
+
+At any time you may invoke any of the other commands, but when it's time to make a release you have to invoke
+
+[source]
+----
+$ ant jreleaser-full-release
+Buildfile: /Home/duke/app/build.xml
+
+jreleaser-full-release:
+Configuring with jreleaser.yml
+ - basedir set to /Home/duke/app
+ - dryrun set to false
+Reading configuration
+Loading properties from /Home/duke/.jreleaser/config.properties
+Validating configuration
+Project version set to 1.0.0
+Release is not snapshot
+Calculating checksums
+Signing files
+Signing is not enabled
+Releasing to https://github.com/duke/app
+ - Generating changelog: out/jreleaser/release/CHANGELOG.md
+ - Uploading app-1.0.0.zip
+ - Uploading app-1.0.0.tar.gz
+ - Uploading checksums.txt
+Preparing distributions
+  - Preparing app distribution
+Packaging distributions
+  - Packaging app distribution
+Uploading distributions
+  - Uploading app distribution
+Announcing release
+Announcing is not enabled. Skipping.
+
+BUILD SUCCESSFUL
+Total time: 2 seconds
+----
+
+This command performs the following actions:
+
+* checksums all artifacts.
+* signs all files (if signing is enabled).
+* creates a release at the chosen Git repository.
+* prepares, packages, and uploads configured packagers (brew, jbang, etc).
+* announces the release.
+
--- a/docs/modules/quick-start/pages/quick-start-cli.adoc
+++ b/docs/modules/quick-start/pages/quick-start-cli.adoc
@@ -1,4 +1,4 @@
-= Quick Start
+= Quick Start - CLI

 Once JReleaser is installed you may initialize its config file by invoking the following command:

@@ -51,6 +51,30 @@ At any time you may invoke any of the other commands, but when it's time to make
 [source]
 ----
 $ jreleaser full-release
+[INFO]  Configuring with jreleaser.yml
+[INFO]    - basedir set to /Home/duke/app
+[INFO]    - dryrun set to false
+[INFO]  Reading configuration
+[INFO]  Loading properties from /Home/duke/.jreleaser/config.properties
+[INFO]  Validating configuration
+[INFO]  Project version set to 1.0.0
+[INFO]  Release is not snapshot
+[INFO]  Calculating checksums
+[INFO]  Signing files
+[INFO]  Signing is not enabled
+[INFO]  Releasing to https://github.com/duke/app
+[INFO]   - Generating changelog: out/jreleaser/release/CHANGELOG.md
+[INFO]   - Uploading app-1.0.0.zip
+[INFO]   - Uploading app-1.0.0.tar.gz
+[INFO]   - Uploading checksums.txt
+[INFO]  Preparing distributions
+[INFO]    - Preparing app distribution
+[INFO]  Packaging distributions
+[INFO]    - Packaging app distribution
+[INFO]  Uploading distributions
+[INFO]    - Uploading app distribution
+[INFO]  Announcing release
+[INFO]  Announcing is not enabled. Skipping.
 ----

 This command performs the following actions:
@@ -59,5 +83,5 @@ This command performs the following actions:
 * signs all files (if signing is enabled).
 * creates a release at the chosen Git repository.
 * prepares, packages, and uploads configured packagers (brew, jbang, etc).
-* announces the release.
+* announces the release (if configured).

--- a/docs/modules/quick-start/pages/quick-start-gradle.adoc
+++ b/docs/modules/quick-start/pages/quick-start-gradle.adoc
@@ -0,0 +1,180 @@
+= Quick Start - Gradle
+
+Your project should be able to produce binary distributions, a feat typically achieved by configuring
+the `link:https://docs.gradle.org/current/userguide/application_plugin.html[application]` plugin.
+
+You also have to configure the xref:tools:gradle.adoc[jreleaser-gradle-plugin]. We recommend using the
+link:https://kordamp.org/kordamp-gradle-plugins/[Kordamp plugins] as they provide additional benefits,
+however their use is optional. A sample project using Kordamp may look like this:
+
+[source,groovy]
+[subs="attributes"]
+.build.gradle
+----
+plugins {
+    id 'java-library'
+    id 'application'
+    id 'org.kordamp.gradle.java-project' version '0.44.0'
+    id 'org.jreleaser' version '{jreleaser-version}'
+}
+
+application {
+    mainClass = 'com.acme.Main'
+}
+
+config {
+    info {
+        name          = 'app'
+        description   = 'App'
+        inceptionYear = '2021'
+        vendor        = 'Acme'
+
+        links {
+            website      = 'https://acme.com/app'
+            issueTracker = 'https://github.com/duke/app/issues'
+            scm          = 'https://github.com/duke/app.git'
+        }
+
+        scm {
+            url                 = 'https://github.com/duke/app'
+            connection          = 'scm:git:https://github.com/duke/app.git'
+            developerConnection = 'scm:git:git@github.com:duke/app.git'
+        }
+        
+        people {
+            person {
+                id    = 'duke'
+                name  = 'Java Duke'
+                roles = ['developer', 'author']
+            }
+        }
+    }
+
+    licensing {
+        licenses {
+            license {
+                id = 'Apache-2.0'
+            }
+        }
+    }
+}
+
+jreleaser {
+    release {
+        github {
+            owner = 'duke'
+            overwrite = true
+        }
+    }
+}
+----
+
+This setup configures the project with the following
+
+* Generate additional JAR manifest entries.
+* Generate a `-sources` JAR file with all sources per project.
+* Configure the javadoc task for each project using information found in the config block, such as author,
+  copyright year, default settings.
+* Generate a `-javadoc` JAR file with the output of the javadoc task, per project.
+* Configure the license plugin with the license details
+* Configure the maven-publish plugin. The `-sources` and `-javadoc` JARs are automatically added to the default publication.
+* Configure the generated POM.
+* Configure the jacoco plugin.
+* Generate a source stats task.
+* Generate a task to collect pretty-printed sources.
+
+Whereas a plain project would look like this:
+
+[source,groovy]
+[subs="attributes"]
+.build.gradle
+----
+plugins {
+    id 'java-library'
+    id 'application'
+    id 'org.jreleaser' version '{jreleaser-version}'
+}
+
+application {
+    mainClass = 'com.acme.Main'
+}
+
+jreleaser {
+    project {
+        website = 'https://acme.com/app'
+        authors = ['Duke']
+        license = 'Apache-2.0'
+    }
+
+    release {
+        github {
+            owner = 'duke'
+            overwrite = true
+        }
+    }
+}
+----
+
+The JReleaser Gradle plugin detects the use of the `application` plugin and automatically configures the output files
+from the `assembleDist` task.
+
+Edit the file to suite your needs. Once you have edited the file you may verify its configuration by invoking
+
+[source]
+----
+$ gradle jreleaserConfig
+----
+
+At any time you may invoke any of the other commands, but when it's time to make a release you have to invoke
+
+[source]
+----
+$ gradle jreleaseFullRelease
+[INFO]  Loading properties from /Home/duke/.jreleaser/config.properties
+[INFO]  Validating configuration
+[INFO]  Project version set to 1.0.0
+[INFO]  Release is not snapshot
+> Task :compileJava
+> Task :processResources NO-SOURCE
+> Task :classes
+> Task :minpom
+> Task :jar
+> Task :startScripts
+> Task :distTar
+> Task :distZip
+> Task :assembleDist
+
+> Task :jreleaserFullRelease
+jreleaser.dryrun set to false
+[INFO]  Calculating checksums
+[INFO]  Signing files
+[INFO]  Signing is not enabled
+[INFO]  Releasing to https://github.com/duke/app
+[INFO]   - Generating changelog: build/jreleaser/release/CHANGELOG.md
+[INFO]   - Uploading app-1.0.0.zip
+[INFO]   - Uploading app-1.0.0.tar.gz
+[INFO]   - Uploading checksums.txt
+[INFO]  Preparing distributions
+[INFO]    - Preparing app distribution
+[INFO]  Packaging distributions
+[INFO]    - Packaging app distribution
+[INFO]  Uploading distributions
+[INFO]    - Uploading app distribution
+[INFO]  Announcing release
+[INFO]  Announcing is not enabled. Skipping.
+
+--------------------------------------------------------------------
+1 projects                                       CONF        EXEC
+--------------------------------------------------------------------
+: .................................. SUCCESS [  0.287 s] [  2.182 s]
+--------------------------------------------------------------------
+----
+
+This command performs the following actions:
+
+* checksums all artifacts.
+* signs all files (if signing is enabled).
+* creates a release at the chosen Git repository.
+* prepares, packages, and uploads configured packagers (brew, jbang, etc).
+* announces the release (if configured).
+
--- a/docs/modules/quick-start/pages/quick-start-maven.adoc
+++ b/docs/modules/quick-start/pages/quick-start-maven.adoc
@@ -0,0 +1,254 @@
+= Quick Start - Maven
+
+Your project should be able to compile, package, and assemble a distribution. We recommend configuring the
+following Maven plugins:
+
+ * link:https://www.mojohaus.org/exec-maven-plugin/[exec-maven-plugin]: execute a main class.
+ * link:https://www.mojohaus.org/appassembler/appassembler-maven-plugin/[appassembler-maven-plugin]: collects application
+ dependencies and generates launcher scripts.
+ * link:http://maven.apache.org/plugins/maven-assembly-plugin/[maven-assembly-plugin]: creates Zip and Tar distributions.
+
+You also have to configure the xref:tools:maven.adoc[jreleaser-maven-plugin]. A sample project may look like this:
+
+[source,xml]
+[subs="attributes,verbatim"]
+.pom.xml
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.acme</groupId>
+  <artifactId>app</artifactId>
+  <version>1.0.0</version>
+
+  <name>app</name>
+  <description>Sample app</description>
+  <url>https://acme.com/app</url>
+  <inceptionYear>2021</inceptionYear>
+
+  <properties>
+    <app.main.class>com.acme.Main</app.main.class>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <java.version>1.8</java.version>
+    <maven.compiler.source>${java.version}</maven.compiler.source>
+    <maven.compiler.target>${java.version}</maven.compiler.target>
+    <app.distribution.directory>${project.build.directory}/distributions/app</app.distribution.directory>
+  </properties>
+
+  <licenses>
+    <license>
+      <name>Apache-2.0</name>
+      <url>https://spdx.org/licenses/Apache-2.0.html</url>
+      <distribution>repo</distribution>
+    </license>
+  </licenses>
+
+  <developers>
+    <developer>
+      <id>duke</id>
+      <name>Java Duke</name>
+    </developer>
+  </developers>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>exec-maven-plugin</artifactId>
+        <version>1.6.0</version>
+        <configuration>
+          <mainClass>${app.main.class}</mainClass>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.8.1</version>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-jar-plugin</artifactId>
+        <version>3.2.0</version>
+        <configuration>
+          <archive>
+            <manifest>
+              <mainClass>${app.main.class}</mainClass>
+            </manifest>
+          </archive>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>appassembler-maven-plugin</artifactId>
+        <version>2.1.0</version>
+        <configuration>
+          <assembleDirectory>${project.build.directory}/binary</assembleDirectory>
+          <repositoryLayout>flat</repositoryLayout>
+          <repositoryName>lib</repositoryName>
+          <programs>
+            <program>
+              <mainClass>${app.main.class}</mainClass>
+              <id>app</id>
+            </program>
+          </programs>
+        </configuration>
+        <executions>
+          <execution>
+            <id>make-distribution</id>
+            <phase>package</phase>
+            <goals>
+              <goal>assemble</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-assembly-plugin</artifactId>
+        <version>3.2.0</version>
+        <configuration>
+          <attach>false</attach>
+          <appendAssemblyId>false</appendAssemblyId>
+          <descriptors>
+            <descriptor>src/main/assembly/assembly.xml</descriptor>
+          </descriptors>
+          <outputDirectory>${app.distribution.directory}</outputDirectory>
+          <workDirectory>${project.build.directory}/assembly/work</workDirectory>
+        </configuration>
+        <executions>
+          <execution>
+            <id>make-distribution</id>
+            <phase>package</phase>
+            <goals>
+              <goal>single</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.jreleaser</groupId>
+        <artifactId>jreleaser-maven-plugin</artifactId>
+        <version>{jreleaser-version}</version>
+        <configuration>
+          <jreleaser>
+            <project>
+              <java>
+                <mainClass>${app.main.class}</mainClass>
+              </java>
+            </project>
+            <release>
+              <github>
+                <owner>duke</owner>
+                <overwrite>true</overwrite>
+              </github>
+            </release>
+            <distributions>
+              <distribution>
+                <name>app</name>
+                <artifacts>
+                  <artifact>
+                    <path>
+                      ${app.distribution.directory}/${project.artifactId}-${project.version}.zip
+                    </path>
+                  </artifact>
+                  <artifact>
+                    <path>
+                      ${app.distribution.directory}/${project.artifactId}-${project.version}.tar.gz
+                    </path>
+                  </artifact>
+                </artifacts>
+              </distribution>
+            </distributions>
+          </jreleaser>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>
+----
+
+Make adjustments as needed. Once you have edited the `pom.xml` you may verify its configuration by invoking
+
+[source]
+----
+$ mvn jreleaser:config
+----
+
+At any time you may invoke any of the other commands, but when it's time to make a release you have to invoke
+
+[source]
+[subs="attributes"]
+----
+$ mvn jreleaser:full-release
+[INFO] Scanning for projects...
+[INFO] 
+[INFO] ----------------------------< com.acme:app >----------------------------
+[INFO] Building app 1.0.0
+[INFO] --------------------------------[ jar ]---------------------------------
+[INFO] 
+[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ app ---
+[INFO] Using 'UTF-8' encoding to copy filtered resources.
+[INFO] skip non existing resourceDirectory /Home/duke/app/src/main/resources
+[INFO] 
+[INFO] --- maven-compiler-plugin:3.8.1:compile (default-compile) @ app ---
+[INFO] Changes detected - recompiling the module!
+[INFO] Compiling 1 source file to /Home/duke/app/target/classes
+[INFO] 
+[INFO] --- maven-resources-plugin:2.6:testResources (default-testResources) @ app ---
+[INFO] Using 'UTF-8' encoding to copy filtered resources.
+[INFO] skip non existing resourceDirectory /Home/duke/app/src/test/resources
+[INFO] 
+[INFO] --- maven-compiler-plugin:3.8.1:testCompile (default-testCompile) @ app ---
+[INFO] No sources to compile
+[INFO] 
+[INFO] --- maven-surefire-plugin:2.12.4:test (default-test) @ app ---
+[INFO] No tests to run.
+[INFO] 
+[INFO] --- maven-jar-plugin:3.2.0:jar (default-jar) @ app ---
+[INFO] Building jar: /Home/duke/app/target/app-1.0.0.jar
+[INFO] 
+[INFO] --- appassembler-maven-plugin:2.1.0:assemble (make-distribution) @ app ---
+[INFO] Installing artifact /Home/duke/app/target/app-1.0.0.jar to /Home/duke/app/target/binary/lib/app-1.0.0.jar
+[INFO] 
+[INFO] --- maven-assembly-plugin:3.2.0:single (make-distribution) @ app ---
+[INFO] Reading assembly descriptor: src/main/assembly/assembly.xml
+[INFO] Building tar: /Home/duke/app/target/distributions/app/app-1.0.0.tar.gz
+[INFO] Building zip: /Home/duke/app/target/distributions/app/app-1.0.0.zip
+[INFO] Copying files to /Home/duke/app/target/distributions/app/app-1.0.0
+[INFO] 
+[INFO] --- jreleaser-maven-plugin:{jreleaser-version}:full-release (default-cli) @ app ---
+[INFO] Loading properties from /Home/duke/.jreleaser/config.properties
+[INFO] Validating configuration
+[INFO] Project version set to 1.0.0
+[INFO] Release is not snapshot
+[INFO] dryrun set to false
+[INFO] Calculating checksums
+[INFO] Signing files
+[INFO] Signing is not enabled
+[INFO] Releasing to https://github.com/duke/app
+[INFO]  - Generating changelog: target/jreleaser/release/CHANGELOG.md
+[INFO]  - Uploading app-1.0.0.zip
+[INFO]  - Uploading app-1.0.0.tar.gz
+[INFO]  - Uploading checksums.txt
+[INFO] Preparing distributions
+[INFO]   - Preparing app distribution
+[INFO] Packaging distributions
+[INFO]   - Packaging app distribution
+[INFO] Uploading distributions
+[INFO]   - Uploading app distribution
+[INFO] Announcing release
+[INFO] Announcing is not enabled. Skipping.
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+----
+
+This command performs the following actions:
+
+* checksums all artifacts.
+* signs all files (if signing is enabled).
+* creates a release at the chosen Git repository.
+* prepares, packages, and uploads configured packagers (brew, jbang, etc).
+* announces the release (if configured).
+