Document gitter

docs/modules/configuration/nav.adoc

@@ -20,6 +20,7 @@
 * xref:files.adoc[]
 * xref:announce/index.adoc[]
 ** xref:announce/discussions.adoc[]
+** xref:announce/gitter.adoc[]
 ** xref:announce/mail.adoc[]
 ** xref:announce/sdkman.adoc[]
 ** xref:announce/slack.adoc[]

docs/modules/configuration/pages/announce/gitter.adoc

@@ -0,0 +1,254 @@
+= Gitter
+
+Posts a message to a link:https://gitter.im/[Gitter] room. You must create a custom webhook for this announcer to work.
+
+1. Log into link:https://gitter.im/[Gitter].
+2. Browse to the room you want to integrate to.
+3. Click on the `Settings` menu and select `Integrations`.
+4. Click on the `CUSTOM` button.
+5. Copy the generated webhook URL.
+
+IMPORTANT: Webhooks are not protected, anyone with access to the webhook URI can send messages to the target room. Prefer
+setting the `JRELEASER_GITTER_WEBHOOK` environment variable over explicitly setting a value in the configuration DSL.
+
+include::partial$legend.adoc[]
+
+[tabs]
+====
+YAML::
++
+[source,yaml]
+[subs="+macros"]
+----
+announce:
+  # icon:dot-circle[]
+  gitter:
+
+    # Enable or disable this announcer.
+    # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
+    # Defaults to `NEVER`.
+    # icon:dot-circle[]
+    active: ALWAYS
+
+    # Defines the connection timeout in seconds.
+    # Defaults to `20`.
+    # icon:dot-circle[]
+    connectTimeout: 20
+
+    # Defines the read timeout in seconds.
+    # Defaults to `60`.
+    # icon:dot-circle[]
+    readTimeout: 6
+
+    # The webhook associated with a specific Gitter room.
+    # If left unspecified, the `JRELEASER_GITTER_WEBHOOK`
+    # environment variable must be defined.
+    # icon:exclamation-triangle[] icon:eye-slash[]
+    webhook: __DO_NOT_SET_HERE__
+
+    # The announcement message.
+    # Review the available xref:configuration:name-templates.adoc[].
+    # icon:dot-circle[] icon:file-alt[]
+    message: icon:rocket[] {{projectNameCapitalized}} {{projectVersion}} has been released! {{releaseNotesUrl}}
+
+    # Path to a template file that contains the message.
+    # Review the available xref:configuration:name-templates.adoc[].
+    # Defaults to `src/jreleaser/templates/gitter.tpl`.
+    # icon:dot-circle[]
+    messageTemplate: path/to/template/gitter.tpl
+----
+TOML::
++
+[source,toml]
+[subs="+macros"]
+----
+# icon:dot-circle[]
+[announce.gitter]
+
+  # Enable or disable this announcer.
+  # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
+  # Defaults to `NEVER`.
+  # icon:dot-circle[]
+  active = "ALWAYS"
+
+  # Defines the connection timeout in seconds.
+  # Defaults to `20`.
+  # icon:dot-circle[]
+  connectTimeout = 20
+
+  # Defines the read timeout in seconds.
+  # Defaults to `60`.
+  # icon:dot-circle[]
+  readTimeout = 60
+
+  # The webhook associated with a specific Gitter room.
+  # If left unspecified, the `JRELEASER_GITTER_WEBHOOK`
+  # environment variable must be defined.
+  # icon:exclamation-triangle[] icon:eye-slash[]
+  webhook = "__DO_NOT_SET_HERE__"
+
+  # The announcement message.
+  # Review the available xref:configuration:name-templates.adoc[].
+  # icon:dot-circle[] icon:file-alt[]
+  message = "icon:rocket[] {{projectNameCapitalized}} {{projectVersion}} has been released! {{releaseNotesUrl}}"
+
+  # Path to a template file that contains the message.
+  # Review the available xref:configuration:name-templates.adoc[].
+  # Defaults to `src/jreleaser/templates/gitter.tpl`.
+  # icon:dot-circle[]
+  messageTemplate = "path/to/template/gitter.tpl"
+----
+JSON::
++
+[source,json]
+[subs="+macros"]
+----
+{
+  "announce": {
+    // icon:dot-circle[]
+    "gitter": {
+
+      // Enable or disable this announcer.
+      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
+      // Defaults to `NEVER`.
+      // icon:dot-circle[]
+      "active": "ALWAYS",
+
+      // Defines the connection timeout in seconds.
+      // Defaults to `20`.
+      // icon:dot-circle[]
+      "connectTimeout": 20,
+
+      // Defines the read timeout in seconds.
+      // Defaults to `60`.
+      // icon:dot-circle[]
+      "readTimeout": 60,
+
+      // The webhook associated with a specific Gitter room.
+      // If left unspecified, the `JRELEASER_GITTER_WEBHOOK`
+      // environment variable must be defined.
+      // icon:exclamation-triangle[] icon:eye-slash[]
+      "webhook": "__DO_NOT_SET_HERE__",
+
+      // The announcement message.
+      // Review the available xref:configuration:name-templates.adoc[].
+      // icon:dot-circle[] icon:file-alt[]
+      "message": "icon:rocket[] {{projectNameCapitalized}} {{projectVersion}} has been released! {{releaseNotesUrl}}",
+
+      // Path to a template file that contains the message.
+      // Review the available xref:configuration:name-templates.adoc[].
+      // Defaults to `src/jreleaser/templates/gitter.tpl`.
+      // icon:dot-circle[]
+      "messageTemplate": "path/to/template/gitter.tpl",
+    }
+  }
+}
+----
+Maven::
++
+[source,xml]
+[subs="+macros,verbatim"]
+----
+<jreleaser>
+  <announce>
+    <!--
+      icon:dot-circle[]
+    -->
+    <gitter>
+
+      <!--
+        Enable or disable this announcer.
+        Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
+        Defaults to `NEVER`.
+        icon:dot-circle[]
+      -->
+      <active>ALWAYS</active>
+
+      <!--
+        Defines the connection timeout in seconds.
+        Defaults to `20`.
+        icon:dot-circle[]
+      -->
+      <connectTimeout>20</connectTimeout>
+
+      <!--
+        Defines the read timeout in seconds.
+        Defaults to `60`.
+        icon:dot-circle[]
+      -->
+      <readTimeout>60</readTimeout>
+
+      <!--
+        The webhook associated with a specific Gitter room.
+        If left unspecified, the `JRELEASER_GITTER_WEBHOOK` environment variable must be defined.
+        icon:exclamation-triangle[] icon:eye-slash[]
+      -->
+      <webhook>__DO_NOT_SET_HERE__</webhook>
+
+      <!--
+        The announcement message.
+        Review the available xref:configuration>templates.adoc[].
+        icon:dot-circle[] icon:file-alt[]
+      -->
+      <message>icon:rocket[] {{projectNameCapitalized}} {{projectVersion}} has been released! {{releaseNotesUrl}}</message>
+
+      <!--
+        Path to a template file that contains the message.
+        Review the available xref:configuration:name-templates.adoc[].
+        Defaults to `src/jreleaser/templates/gitter.tpl`.
+        icon:dot-circle[]
+      -->
+      <messageTemplate>path/to/template/gitter.tpl</messageTemplate>
+    </gitter>
+  </announce>
+</jreleaser>
+----
+Gradle::
++
+[source,groovy]
+[subs="+macros"]
+----
+jreleaser {
+  announce {
+    // icon:dot-circle[]
+    gitter {
+
+      // Enable or disable this announcer.
+      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
+      // Defaults to `NEVER`.
+      // icon:dot-circle[]
+      active = 'ALWAYS'
+
+      // Defines the connection timeout in seconds.
+      // Defaults to `20`.
+      // icon:dot-circle[]
+      connectTimeout = 20
+
+      // Defines the read timeout in seconds.
+      // Defaults to `60`.
+      // icon:dot-circle[]
+      readTimeout = 60
+
+      // The webhook associated with a specific Gitter room.
+      // If left unspecified, the `JRELEASER_GITTER_WEBHOOK`
+      // environment variable must be defined.
+      // icon:exclamation-triangle[] icon:eye-slash[]
+      webhook = '__DO_NOT_SET_HERE__'
+
+      // The announcement message.
+      // Review the available xref:configuration:name-templates.adoc[].
+      // icon:dot-circle[] icon:file-alt[]
+      message = 'icon:rocket[] {{projectNameCapitalized}} {{projectVersion}} has been released! {{releaseNotesUrl}}'
+
+      // Path to a template file that contains the message.
+      // Review the available xref:configuration:name-templates.adoc[].
+      // Defaults to `src/jreleaser/templates/gitter.tpl`.
+      // icon:dot-circle[]
+      messageTemplate = 'path/to/template/gitter.tpl'
+    }
+  }
+}
+----
+====
+
+You may define either `message` or `messageTemplate`, with the former taking precedence over the latter.

docs/modules/configuration/pages/announce/twitter.adoc

@@ -300,7 +300,7 @@ jreleaser {
 
       // The announcement message.
       // Review the available xref:configuration:name-templates.adoc[].
-      // icon:dot-circle[]
+      // icon:dot-circle[] icon:file-alt[]
       status = 'icon:rocket[] {{projectNameCapitalized}} {{projectVersion}} has been released! {{releaseNotesUrl}}'
     }
   }

docs/modules/configuration/pages/announce/zulip.adoc

@@ -178,7 +178,7 @@ JSON::
 
       // The announcement message.
       // Review the available xref:configuration:name-templates.adoc[].
-      // icon:dot-circle[]
+      // icon:dot-circle[] icon:file-alt[]
       "message": "icon:rocket[] {{projectNameCapitalized}} {{projectVersion}} has been released! {{releaseNotesUrl}}",
 
       // Path to a template file that contains the message.
@@ -260,7 +260,7 @@ Maven::
       <!--
         The announcement message.
         Review the available xref:configuration>templates.adoc[].
-        icon:dot-circle[]
+        icon:dot-circle[] icon:file-alt[]
       -->
       <message>icon:rocket[] {{projectNameCapitalized}} {{projectVersion}} has been released! {{releaseNotesUrl}}</message>
 
@@ -327,7 +327,7 @@ jreleaser {
 
       // The announcement message.
       // Review the available xref:configuration:name-templates.adoc[].
-      // icon:dot-circle[]
+      // icon:dot-circle[] icon:file-alt[]
       message = 'icon:rocket[] {{projectNameCapitalized}} {{projectVersion}} has been released! {{releaseNotesUrl}}'
 
       // Path to a template file that contains the message.

docs/modules/configuration/pages/environment.adoc

@@ -224,6 +224,14 @@ The following key/values may be defined in the properties file or as environment
 | JRELEASER_SNAP_GITEA_TOKEN  | a Gitea personal token
 |===
 
+== Gitter
+
+[%header, cols="<1,<1", width="100%"]
+|===
+| Key                      | Description
+| JRELEASER_GITTER_WEBHOOK | the webhook URL
+|===
+
 == Mail
 
 [%header, cols="<1,<1", width="100%"]