feat: improve docs and branding

.github/ISSUE_TEMPLATE/01-bug.yml

@@ -0,0 +1,113 @@
+---
+name: Report a Bug
+description: File a bug report for spotless-cli
+title: "[BUG]: "
+labels: ["bug-unconfirmed"]
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting a bug! Please take the time to fill out the following form so that we can
+        understand and reproduce the issue.
+
+        Before submitting:
+        - Have you checked for **existing issues** in both [`spotless-cli`](https://github.com/diffplug/spotless-cli/issues) and [`spotless`](https://github.com/diffplug/spotless/issues)?
+        - Is this issue about formatting behavior that might belong to the [`spotless`](https://github.com/diffplug/spotless) library instead?
+
+  - type: checkboxes
+    id: pre_submission_checklist
+    attributes:
+      label: Pre-submission checks
+      description: Please confirm the following before submitting.
+      options:
+        - label: I have searched for [existing issues in spotless-cli](https://github.com/diffplug/spotless-cli/issues).
+          required: true
+        - label: I have searched for [existing issues in spotless](https://github.com/diffplug/spotless/issues).
+          required: true
+        - label: This issue is specific to `spotless-cli`, and not just the formatting logic in `spotless-lib`.
+          required: true
+
+  - type: textarea
+    id: cli-version
+    attributes:
+      label: spotless-cli version
+      description: Run `spotless --version` to get the version.
+      placeholder: |
+        e.g.
+        --------------------------------------------------
+        🧼 Spotless CLI 0.1.0
+        --------------------------------------------------
+
+        spotless-lib:       3.1.0
+        spotless-lib-extra: 3.1.0
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system and architecture
+      options:
+        - macOS (Intel)
+        - macOS (Apple Silicon / ARM)
+        - Linux (Intel)
+        - Linux (ARM)
+        - Windows (x64)
+        - I don't know (Please specify in the comment section)
+    validations:
+      required: true
+
+# # # #
+  - type: textarea
+    id: command
+    attributes:
+      label: CLI command used
+      description: The exact `spotless` command you ran.
+      placeholder: |
+        e.g. spotless --target '**/src/**/*.java' \
+                google-java-format \
+                license-header --header='/* (c) DiffPlug $YEAR */'
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Description of the problem
+      description: What did you expect to happen, and what actually happened?
+      placeholder: Describe the unexpected behavior in detail.
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs from the command line
+      description: Please re-run your command with `-vvvvv` and paste the output here.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproducibility
+    attributes:
+      label: Steps to reproduce
+      description: How can we reproduce the issue? Include the minimum files and configuration needed.
+      placeholder: |
+        1. Create a file with the following content...
+        2. Use this `.spotless.yaml` config...
+        3. Run `spotless apply` and observe...
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Include any error logs, stack traces, screenshots, or references to related issues.
+      placeholder: |
+        - stack trace here
+        - related issue: #123
+        - logs from console...
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/02-feature-request.yml

@@ -0,0 +1,68 @@
+name: Feature request
+description: Suggest a new feature or enhancement for spotless-cli
+title: "[Feature Request]: "
+labels: ["enhancement"]
+assignees: []
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for suggesting a feature!
+
+        Please make sure your idea aligns with the goals of `spotless-cli`, which is a thin CLI layer around `spotless-lib`.
+
+  - type: textarea
+    id: cli-version
+    attributes:
+      label: spotless-cli version (if relevant)
+      description: If your request is based on a current limitation or behavior.
+      placeholder: |
+        e.g.
+        --------------------------------------------------
+        🧼 Spotless CLI 0.1.0
+        --------------------------------------------------
+
+        spotless-lib:       3.1.0
+        spotless-lib-extra: 3.1.0
+    validations:
+      required: false
+
+  - type: textarea
+    id: feature-description
+    attributes:
+      label: Describe the feature
+      description: What functionality would you like to see added?
+      placeholder: |
+        I would like to see support for...
+        It would help because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation and use case
+      description: Why is this feature important to you? What problem does it solve?
+      placeholder: This feature would be useful for projects that...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Have you considered any workarounds or other tools?
+      placeholder: Currently, I'm working around it by...
+    validations:
+      required: false
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Feature scope
+      description: Where do you think this feature belongs?
+      options:
+        - label: This should be implemented in `spotless-cli`.
+        - label: This may belong in `spotless-lib` instead.
+        - label: Not sure.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,6 @@
+---
+blank_issues_enabled: true
+contact_links:
+  - name: Spotless Core Library Issues
+    url: https://github.com/diffplug/spotless/issues
+    about: Report an issue with the Spotless Core Library (if you suspect the bug to be inside the formatter itself).

README.md

@@ -1,22 +1,22 @@
-# <img align="left" src="../_images/spotless_logo.png"> Spotless Command Line Interface CLI
+# <img align="left" src="docs/logo/spotless_banner.png" alt="Banner introducing spotless cli"> Spotless Command Line Interface CLI
 
 _Keep your code Spotless from the command line_
 
 <!---freshmark shields
 output = [
-  link(shield('Changelog', 'changelog', '{{versionLast}}', 'blue'), 'CHANGES.md'),
+  link(shield('SpotlessCLI Version', 'latest-version', '{{spotlessVersion}}', 'blue'), 'CHANGES.md'),
   '',
-  link(shield('OS Win', 'OS', 'Windows', 'blueviolet'), 'README.md'),
-  link(shield('OS Linux', 'OS', 'Linux', 'blueviolet'), 'README.md'),
-  link(shield('OS macOS', 'OS', 'macOS', 'blueviolet'), 'README.md'),
+  link(shield('OS Win', 'OS', 'Windows', 'blueviolet'), '#installation-on-windows'),
+  link(shield('OS Linux', 'OS', 'Linux', 'blueviolet'), '#installation-on-macos-and-linux'),
+  link(shield('OS macOS', 'OS', 'macOS', 'blueviolet'), '#installation-on-macos-and-linux'),
   ].join('\n')
 -->
 
-[![Changelog](https://img.shields.io/badge/changelog-versionLast%3DUNKNOWN-blue.svg)](CHANGES.md)
+[![SpotlessCLI Version](https://img.shields.io/badge/latest--version-0.1.0-blue.svg)](CHANGES.md)
 
-[![OS Win](https://img.shields.io/badge/OS-Windows-blueviolet.svg)](README.md)
-[![OS Linux](https://img.shields.io/badge/OS-Linux-blueviolet.svg)](README.md)
-[![OS macOS](https://img.shields.io/badge/OS-macOS-blueviolet.svg)](README.md)
+[![OS Win](https://img.shields.io/badge/OS-Windows-blueviolet.svg)](#installation-on-windows)
+[![OS Linux](https://img.shields.io/badge/OS-Linux-blueviolet.svg)](#installation-on-macos-and-linux)
+[![OS macOS](https://img.shields.io/badge/OS-macOS-blueviolet.svg)](#installation-on-macos-and-linux)
 
 <!---freshmark /shields -->
 
@@ -57,7 +57,9 @@ output = [
 
 ## Installation
 
-To install with Homebrew on macOS or Linux:
+### Installation on macOS and Linux
+
+To install with [Homebrew](https://brew.sh/) on macOS or Linux:
 
 ```shell
 brew install diffplug/tap/spotless-cli
@@ -67,10 +69,12 @@ brew tap diffplug/tap
 brew install spotless-cli
 ```
 
-To install with Chocolatey on Windows:
+### Installation on Windows
+
+To install with [Chocolatey](https://chocolatey.org/) on Windows:
 
 ```shell
-choco install ...
+choco install spotless-cli
 ```
 
 Alternatively, you can download the latest binary for your system from the [releases page](https://...) and add it to your PATH.

build-logic/build.gradle

@@ -20,6 +20,7 @@ dependencies {
 	implementation 'com.gradleup.shadow:shadow-gradle-plugin:8.3.6'
 	implementation 'org.graalvm.buildtools:native-gradle-plugin:0.10.5'
 	implementation libs.bundles.spotless.libs
+	implementation libs.spotless.plugin.gradle
 }
 
 spotless {

build-logic/src/main/groovy/buildlogic.spotless-markdown-conventions.gradle

@@ -1,23 +1,65 @@
 import com.diffplug.spotless.cli.picocli.usage.DocumentedUsages
+import com.diffplug.gradle.spotless.FreshMarkExtension
+import com.oracle.svm.core.annotate.Inject
 
 plugins {
 	id 'buildlogic.spotless-common-conventions'
+	id 'com.diffplug.spotless-changelog'
 }
 
+Action<FreshMarkExtension> freshmarkSetup = new Action<FreshMarkExtension>(){
+
+			void execute(FreshMarkExtension freshmark) {
+				freshmark.target '*.md'
+				freshmark.properties(new FreshmarkPropertiesAction(rootProject, project))
+				freshmark.properties {
+					it.put('changeThisValueToForceCacheMiss', '1f31705c-b1c6-4bce-9831-98881431b721')
+				}
+				freshmark.prettier() // prettier for markdown formatting
+				freshmark.endWithNewline()
+			}
+		}
+
 spotless {
 	freshmark {
 		// freshmark for keeping markdown files up to date
-		target '*.md'
-		// provide lib versions to freshmark
-		properties(new FreshmarkPropertiesAction(rootProject, project))
-		properties {
-			it.put('changeThisValueToForceCacheMiss', '1f31705c-b1c6-4bce-9831-98881431b721')
+		freshmarkSetup.execute(it)
+	}
+}
+
+interface MarkdownProjInjections {
+	@javax.inject.Inject
+	ExecOperations getExecOperations()
+}
+
+// if this freshmark has a changelog file, then it has version-sensitive content
+if (tasks.names.contains('changelogCheck')) {
+	// create a freshmark apply task manually
+	FreshMarkExtension freshmark = new FreshMarkExtension(spotless)
+	freshmarkSetup.execute(freshmark)
+	// override version for this task, we want to use versionNext because versionLast is bumped after evaluation, so peek ahead
+	freshmark.properties {
+		it.put('spotlessVersion', rootProject.spotlessChangelog.versionNext)
+	}
+	def changelogBumpFreshmark = freshmark.createIndependentApplyTask('changelogBumpFreshmark')
+	// freshmark should run after the changelog bump
+	changelogBumpFreshmark.dependsOn tasks.named('changelogBump')
+
+	def changelogBumpFreshmarkGitAdd = tasks.register('changelogBumpFreshmarkGitAdd') {
+		def execOps = project.objects.newInstance(MarkdownProjInjections).execOperations
+		// this git add should run after the freshmark
+		dependsOn(changelogBumpFreshmark)
+		// do the git add
+		doLast {
+			execOps.exec { commandLine 'git', 'add' , '*.md' }
 		}
-		prettier() // prettier for markdown formatting
-		endWithNewline()
+	}
+	tasks.named('changelogPush').configure {
+		dependsOn changelogBumpFreshmarkGitAdd
 	}
 }
 
+
 class FreshmarkPropertiesAction implements Action<Map<String, Object>> {
 
 	private final Project rootProject
@@ -34,6 +76,7 @@ class FreshmarkPropertiesAction implements Action<Map<String, Object>> {
 		properties.putAll(versionsCollected)
 		def usageHelps = getUsageHelps()
 		properties.putAll(usageHelps)
+		properties.put('spotlessVersion', rootProject.spotlessChangelog.versionLast)
 	}
 
 	Map<String, String> getVersionsCollected() {

build.gradle

@@ -3,9 +3,9 @@ import com.diffplug.spotless.cli.io.CopySingleTemplateFileTask
 plugins {
 	id 'buildlogic.spotless-gradle-conventions'
 	id 'buildlogic.spotless-json-conventions'
+	id 'buildlogic.changelog-conventions'
 	id 'buildlogic.spotless-markdown-conventions'
 	id 'buildlogic.spotless-yaml-conventions'
-	id 'buildlogic.changelog-conventions'
 }
 
 subprojects {

gradle/libs.versions.toml

@@ -11,6 +11,7 @@ picocli = "4.7.6"
 selfie = "2.5.1"
 slf4j = "2.0.17"
 spotless-lib = "3.1.0"
+spotless-plugin-gradle = "7.0.2"
 
 [libraries]
 annotations = { module = "org.jetbrains:annotations", version.ref = "annotations" }
@@ -31,6 +32,7 @@ slf4j-api = { module = "org.slf4j:slf4j-api", version.ref = "slf4j" }
 slf4j-binding = { module = "org.slf4j:slf4j-jdk14", version.ref = "slf4j" }
 spotless-lib = { module = "com.diffplug.spotless:spotless-lib", version.ref = "spotless-lib" }
 spotless-lib-extra = { module = "com.diffplug.spotless:spotless-lib-extra", version.ref = "spotless-lib" }
+spotless-plugin-gradle = { module = "com.diffplug.spotless:spotless-plugin-gradle", version.ref = "spotless-plugin-gradle" }
 
 [bundles]
 durian-libs = ["durian-core", "durian-io", "durian-collect"]

jreleaser.yml.template

@@ -13,6 +13,11 @@ project:
   authors:
     - DiffPlug
   inceptionYear: "2025"
+  icons:
+    - url: https://raw.githubusercontent.com/diffplug/spotless-cli/docs/logo/spotless-brush-256.png
+      height: 256
+      width: 256
+      primary: true
 
 distributions:
   spotless-cli: