basic docs

Author: countableSet

build.gradle.kts

@@ -19,7 +19,7 @@ dependencies {
 }
 
 gradlePlugin {
-    website.set("https://semantic-version.gradle.poolside.dev")
+    website.set("https://github.com/countableSet/semantic-version-plugin")
     vcsUrl.set("https://github.com/countableSet/semantic-version-plugin")
 
     plugins {

docs/README.md

@@ -0,0 +1,119 @@
+<!-- Generated with https://github.com/thlorenz/doctoc -->
+<!-- doctoc docs/README.md >
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Change Log](#change-log)
+- [Usage](#usage)
+  - [Auto mode](#auto-mode)
+  - [Manual mode](#manual-mode)
+- [Gradle Version Requirement](#gradle-version-requirement)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+Gradle plugin to auto-increments the patch version on each call to the `publish` task by looking up the most recent version published in the publishing maven repository and adds it by one.
+
+Tested to work in the following scenarios:
+
+* Single root project publication
+* Single and multiple subprojects publication
+* BOM references via `api(platform(project(":bom")))` and `java-platform` plugin
+* Manual versioning, prevents the task from publishing if the version isn't different from the one in maven
+
+![example](semantic-version-plugin.svg)
+
+## Change Log
+
+See [releases](https://github.com/countableSet/semantic-version-plugin/releases) for changes.
+
+* 0.2.x compatible with Java 11
+  ** 0.2.0 set compatability to Java 11, bump dependency versions, and upgrade gradle to 8.1
+* 0.1.x compatible with Java 8
+  ** 0.1.5 fix bug when the plugin wasn't applying correct to root projects without jars
+  ** 0.1.4 fix bug when major or minor version was bump was computed incorrectly
+  ** 0.1.3 adds manual mode flag to skip publishing when artifact already exists
+  ** 0.1.2 fix bug with version finder
+  ** 0.1.1 unknown
+  ** 0.1.0 unknown
+
+## Usage
+
+[Plugins Portal](https://plugins.gradle.org/plugin/dev.poolside.gradle.semantic-version)
+
+```kotlin
+plugins {
+  `maven-publish`
+  id("dev.poolside.gradle.semantic-version") version "{version}"
+}
+```
+
+```sh
+$ ./gradlw publish
+[...]
+> Task :semanticVersion
+Resolved published version of 'dev.poolside.test:my-library:0.1.4' to '0.1.5'
+[...]
+```
+
+### Auto mode
+
+Basic full example, but it can also be used for subprojects and bom subprojects. However, make sure the publication version number is in the format of `[\d]+\.[\d]+`.
+
+```kotlin
+plugins {
+  java
+  `maven-publish`
+  id("dev.poolside.gradle.semantic-version") version "{version}"
+}
+repositories {
+  mavenCentral()
+}
+
+group = "dev.poolside.test"
+version = "0.1"
+
+publishing {
+  publications {
+    create<MavenPublication>("mavenJava") { 
+      artifactId = "my-library"
+      from(components["java"])
+    }
+  }
+}
+```
+
+### Manual mode
+
+If there's a scenario in which you want to manually increment the semantic version. Therefore, the plugin will disable publishing if the version already exists in the repository.
+
+```kotlin
+semanticVersion {
+  manual = true
+}
+```
+
+## Gradle Version Requirement
+
+The plugin now requires Gradle version 8.11+ to access new access.
+
+```sh
+❯ gr semanticVersion
+> Task :client:semanticVersion FAILED
+
+FAILURE: Build failed with an exception.
+
+* What went wrong:
+  Execution failed for task ':client:semanticVersion'.
+> org/gradle/api/internal/initialization/StandaloneDomainObjectContext
+
+* Try:
+> Run with --stacktrace option to get the stack trace.
+> Run with --info or --debug option to get more log output.
+> Run with --scan to get full insights.
+> Get more help at https://help.gradle.org.
+
+BUILD FAILED in 1s
+2 actionable tasks: 2 executed
+```

docs/antora.yml

@@ -0,0 +1,92 @@
+<!-- Generated with https://github.com/thlorenz/doctoc -->
+<!-- doctoc docs/development.md >
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Development](#development)
+- [Gradle Plugin Publishing](#gradle-plugin-publishing)
+- [References](#references)
+  - [General](#general)
+  - [pom.withXml](#pomwithxml)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Development
+
+[Gradle docs](https://docs.gradle.org/current/userguide/writing_plugins.html) on writing plugins.
+
+Publish to mavenLocal
+
+```sh
+❯ gr publishToMavenLocal
+
+BUILD SUCCESSFUL in 5s
+11 actionable tasks: 8 executed, 3 up-to-date
+```
+
+Add to `settings.gradle` file in client project and change the version `id 'dev.poolside.gradle.semantic-version' version '1.0.0'`
+
+```groovy
+pluginManagement {
+  repositories {
+    mavenLocal()
+  }
+}
+```
+
+## Gradle Plugin Publishing
+
+* [plugin docs](https://plugins.gradle.org/docs/publish-plugin-new)
+* [user account](https://plugins.gradle.org/u/poolside)
+
+
+It's easier to set up credentials via the login task then doing it manually in the gradle.properties file
+
+```sh
+❯ gr login
+```
+
+Then run the publishing task:
+
+```sh
+❯ gr publishPlugins
+
+> Task :publishPlugins
+Publishing plugin dev.poolside.gradle.semantic-version version 0.1.0
+Thank you. Your new plugin dev.poolside.gradle.semantic-version has been submitted for approval by Gradle engineers. The request should be processed within the next few days, at which point you will be contacted via email.
+Publishing artifact build/publications/pluginMaven/module.json
+Publishing artifact build/publications/pluginMaven/pom-default.xml
+Publishing artifact build/libs/semantic-version-plugin-0.1.0.jar
+Publishing artifact build/libs/semantic-version-plugin-0.1.0-sources.jar
+Publishing artifact build/libs/semantic-version-plugin-0.1.0-javadoc.jar
+Activating plugin dev.poolside.gradle.semantic-version version 0.1.0
+
+Deprecated Gradle features were used in this build, making it incompatible with Gradle 8.0.
+
+You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.
+
+See https://docs.gradle.org/7.4.2/userguide/command_line_interface.html#sec:command_line_warnings
+
+BUILD SUCCESSFUL in 5s
+10 actionable tasks: 7 executed, 3 up-to-date
+```
+
+## References
+
+Information that I found helpful when writing this plugin
+
+### General
+
+* https://github.com/nebula-plugins/nebula-publishing-plugin
+  * [MavenResolvedDependenciesPlugin](https://github.com/nebula-plugins/nebula-publishing-plugin/blob/aee3fb093c622e7b7c9eb75cb6dc2838c2bcf340/src/main/groovy/nebula/plugin/publishing/maven/MavenResolvedDependenciesPlugin.groovy)
+* [editing pom info](https://stackoverflow.com/questions/20959558/in-gradle-how-can-i-generate-a-pom-file-with-dynamic-dependencies-resolved-to-t)
+
+### pom.withXml
+
+Editing groovy dom nodes/nodelists/etc is a pain in kotlin. I found these links helpful.
+
+* [kotlinx.dom](https://github.com/Kotlin/kotlinx.dom/blob/0fe219d942047468b361dc0594f1c443ebcf26c3/src/main/kotlin/Dom.kt)
+* [kotlin-dsl-sample issue](https://github.com/gradle/kotlin-dsl-samples/issues/225)
+* [groovy example](https://github.com/nebula-plugins/nebula-publishing-plugin/blob/575b55c72151e0fae35c4aea69ff77ae8db57455/src/main/groovy/nebula/plugin/publishing/maven/MavenRemoveInvalidDependenciesPlugin.groovy)