Backport "Mill sonatype publishing doc" (com-lihaoyi#5107)

Backport of com-lihaoyi#4928 to 0.12.x

---------

Co-authored-by: Jeffrey <[email protected]>

Author: lihaoyi

contrib/sonatypecentral/readme.adoc

@@ -1,4 +1,4 @@
-= Sonatype Central
+= Sonatype Central (Plugin Moved to Scalalib)
 :page-aliases: Plugin_Sonatype_Central.adoc
 
 This plugin allows users to publish open-source packages to Maven Central via the Sonatype Central portal.

contrib/sonatypecentral/src/mill/contrib/sonatypecentral/package.scala

@@ -50,7 +50,6 @@ include::partial$example/extending/imports/3-contrib-import.adoc[]
 * xref:contrib/proguard.adoc[]
 * xref:contrib/scalapblib.adoc[]
 * xref:contrib/scoverage.adoc[]
-* xref:contrib/sonatypecentral.adoc[]
 * xref:contrib/testng.adoc[]
 * xref:contrib/twirllib.adoc[]
 * xref:contrib/versionfile.adoc[]

docs/modules/ROOT/pages/extending/contrib-plugins.adoc

@@ -33,6 +33,10 @@ include::partial$example/javalib/publishing/6-jpackage.adoc[]
 
 include::partial$example/javalib/publishing/2-publish-module.adoc[]
 
+== Publishing to Sonatype Maven Central
+
+include::partial$example/javalib/publishing/9-publish-module-sonatype.adoc[]
+
 == Checking API compatibility
 
 Mill provides the ability to check API changes with the https://revapi.org/revapi-site/main/index.html[Revapi] analysis and change tracking tool.

docs/modules/ROOT/pages/javalib/publishing.adoc

@@ -23,6 +23,10 @@ include::partial$example/kotlinlib/publishing/8-native-image-libs.adoc[]
 
 include::partial$example/kotlinlib/publishing/2-publish-module.adoc[]
 
+== Publishing to Sonatype Maven Central
+
+include::partial$example/kotlinlib/publishing/3-publish-module-sonatype.adoc[]
+
 include::partial$Publishing_Footer.adoc[]
 
 == `jlink` and `jpackage`

docs/modules/ROOT/pages/kotlinlib/publishing.adoc

@@ -24,6 +24,10 @@ include::partial$example/scalalib/publishing/8-native-image-libs.adoc[]
 
 include::partial$example/scalalib/publishing/2-publish-module.adoc[]
 
+== Publlishing to Sonatype Maven Central
+
+include::partial$example/scalalib/publishing/3-publish-module-sonatype.adoc[]
+
 include::partial$Publishing_Footer.adoc[]
 
 == `jlink` and `jpackage`

docs/modules/ROOT/pages/scalalib/publishing.adoc

@@ -1,4 +1,8 @@
-== Publishing to Sonatype Maven Central
+This example configured for publishing to Sonatype Maven Central via
+Central Portal. Extends `SonatypeCentralPublishModule` which provides
+simplified publishing tasks without requiring Nexus repository manager.
+
+== Instructions for Publishing to Maven Central via Central Portal
 
 Once you've mixed in `PublishModule`, apart from publishing locally, you can also publish
 your project's modules to maven central
@@ -17,6 +21,14 @@ for publishing:
 
 [source,bash]
 ----
+# Sonatype Central Portal needs your public key to be uploaded so it can use for verification of artifacts from their end.
+#
+# Send your public key to ubuntu server so Sonatype Maven Central can use for verification of the artifacts
+gpg --keyserver  keyserver.ubuntu.com --send-keys $LONG_ID
+#
+# Check the server for information about the public key. information will be displayed if found
+gpg --keyserver  keyserver.ubuntu.com --recv-keys $LONG_ID
+#
 # The LHS and RHS of the User Token, accessible through the sonatype
 # website `Profile` / `User Token` / `Access User Token`
 export MILL_SONATYPE_USERNAME=...
@@ -44,6 +56,77 @@ export MILL_PGP_PASSPHRASE=...
 
 === Publishing
 
+You can publish all eligible modules in your Mill project using 
+`mill.scalalib.SonatypeCentralPublishModule/`:
+
+[source,console]
+----
+> mill mill.scalalib.SonatypeCentralPublishModule/
+----
+
+You can also specify individual modules you want to publish in two ways:
+
+[source,console]
+----
+> mill foo.publishSonatypeCentral
+----
+
+[source.console]
+----
+> mill mill.scalalib.SonatypeCentralPublishModule/ --publishArtifacts foo.publishArtifacts
+----
+
+=== Publishing Using Github Actions
+
+
+To publish on Github Actions, you can use something like this:
+
+```yaml
+# .github/workflows/publish-artifacts.yml
+name: Publish Artifacts
+on:
+  push:
+    tags:
+      - '**'
+  workflow_dispatch:
+jobs:
+  publish-artifacts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+      - run: ./mill mill.scalalib.SonatypeCentralPublishModule/
+        env:
+          MILL_PGP_PASSPHRASE: ${{ secrets.MILL_PGP_PASSPHRASE }}
+          MILL_PGP_SECRET_BASE64: ${{ secrets.MILL_PGP_SECRET_BASE64 }}
+          MILL_SONATYPE_PASSWORD: ${{ secrets.MILL_SONATYPE_PASSWORD }}
+          MILL_SONATYPE_USERNAME: ${{ secrets.MILL_SONATYPE_USERNAME }}
+```
+
+Where `MILL_PGP_PASSPHRASE`, `MILL_PGP_SECRET_BASE64`, `MILL_SONATYPE_PASSWORD`, and
+`MILL_SONATYPE_USERNAME` configured for the repository's or organization's Github Actions
+workflows. See
+https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions[Using Secrets in Github Actions]
+for more details.
+
+
+== Instructions for Publishing to Maven Central via Legacy OSSHR (Deprecated)
+
+[NOTE]
+--
+Publishing via the legacy OSSRH (OSS Repository Hosting) is deprecated and will reach end-of-life on June 30, 2025,
+due to the retirement of https://help.sonatype.com/en/sonatype-nexus-repository-2-sunsetting-information.html[Sonatype’s Nexus Repository Manager v2]. Sonatype now recommends using the https://central.sonatype.org/publish/publish-portal-guide/[Central Portal] for all new publishing.
+Migration is strongly encouraged to avoid disruptions. For full details, see the https://central.sonatype.org/news/20250326_ossrh_sunset/[OSSRH Sunset Announcement].
+--
+
+Just like publishing via the Central Portal requires a GPG key and publish secrets, 
+publishing via the legacy OSSHR(OSS Repository Hosting) also requires them.
+
+=== Publishing
+
 You can publish all eligible modules in your Mill project using
 the xref:fundamentals/modules.adoc#_default_tasks[default task] of the
 xref:fundamentals/modules.adoc#_external_modules[External Module] `mill.scalalib.PublishModule`:
@@ -141,6 +224,78 @@ mill mill.scalalib.PublishModule/ \
 ----
 
 
+== `SonatypeCentralPublishModule` Configurations
+
+This module provides settings and a CLI interface for publishing artifacts to Sonatype Maven Central.
+You can configure it through your `build.mill` file or by passing command-line options to it.
+
+=== Module-Level Settings
+You can override default publishing settings in your build.mill like this:
+
+[source,scala]
+----
+object mymodule extends SonatypeCentralPublishModule {
+  override def sonatypeCentralGpgArgs: T[String] = "--batch, --yes, -a, -b"
+
+  override def sonatypeCentralConnectTimeout: T[Int] = 5000
+
+  override def sonatypeCentralReadTimeout: T[Int] = 60000
+
+  override def sonatypeCentralAwaitTimeout: T[Int] = 120 * 1000
+
+  override def sonatypeCentralShouldRelease: T[Boolean] = true
+  ...
+}
+----
+
+=== Argument Reference
+
+==== publishAll
+
+The `publishAll` task can be called from the CLI. If a required value is not provided via the CLI option,
+it will fall back to an environment variable (if available) or raise an error if missing.
+
+The `./mill mill.scalalib.SonatypeCentralPublishModule/publishAll` takes the following options:
+
+`username`: The username for calling the Sonatype Central publishing api. Defaults to the `SONATYPE_USERNAME` environment variable if unset. If neither the parameter nor the environment variable are set, an error will be thrown. +
+
+`password`: The password for calling the Sonatype Central publishing api. Defaults to the `SONATYPE_PASSWORD` environment variable if unset. If neither the parameter nor the environment variable are set, an error will be thrown. +
+
+`gpgArgs`: Arguments to pass to the gpg package for signing artifacts. Uses the `MILL_PGP_PASSPHRASE` environment variable if set. _Default: `[--passphrase=$MILL_PGP_PASSPHRASE], --no-tty, --pinentry-mode, loopback, --batch, --yes, -a, -b`._ +
+
+`publishArtifacts`: The command for generating all publishable artifacts (ex. `__.publishArtifacts`). Required. +
+
+`readTimeout`:  The timeout for receiving a response from Sonatype Central after the initial connection has occurred. _Default: 60000._ +
+
+`awaitTimeout`: The overall timeout for all retries (including exponential backoff) of the bundle upload. _Default: 120 * 1000._ +
+
+`connectTimeout`: The timeout for the initial connection to Sonatype Central if there is no response. _Default: 5000._ +
+
+`shouldRelease`: Whether the bundle should be automatically released when uploaded to Sonatype Central. If `false`, the bundle will still be uploaded, but users will need to manually log in to Sonatype Central and publish the bundle from the portal. _Default: true_ +
+
+`bundleName`: If set, all packages will be uploaded in a single bundle with the given name. If unset, packages will be uploaded separately. Recommended bundle name syntax: groupName-artifactId-versionNumber. As an example, if publishing the `com.lihaoyi` `requests` package, without the bundle name, four different bundles will be uploaded, one for each scala version supported. With a bundle name of `com.lihaoyi-requests-<new_version>`, a single bundle will be uploaded that contains all packages across scala versions. It is recommended to set the bundle name, so that packages can be verified and deployed together. _Default: No bundle name is set and packages will be uploaded separately_
+
+==== Example command
+
+----
+$ mill -i \
+mill.scalalib.SonatypeCentralPublishModule/publishAll \
+--username myusername \
+--password mypassword \
+--gpgArgs --passphrase=$MILL_PGP_PASSPHRASE,--no-tty,--pinentry-mode,loopback,--batch,--yes,-a,-b \
+--publishArtifacts __.publishArtifacts \
+--readTimeout  36000 \
+--awaitTimeout 36000 \
+--connectTimeout 36000 \
+--shouldRelease false \
+--bundleName com.lihaoyi-requests:1.0.0
+----
+
+==== publishSonatypeCentral
+
+The `__.publishSonatypeCentral` command takes the `username` and `password` arguments, documented above.
+
+
 == Publishing to other repositories
 
 While Sonatype Maven Central is the default publish repository for JVM ecosystem projects,
@@ -149,4 +304,3 @@ there are also others that you can use. Mill supports these largely through cont
 * xref:contrib/codeartifact.adoc[]
 * xref:contrib/artifactory.adoc[]
 * xref:contrib/bintray.adoc[]
-* xref:contrib/sonatypecentral.adoc[]

docs/modules/ROOT/partials/Publishing_Footer.adoc

@@ -0,0 +1,20 @@
+//// SNIPPET:BUILD
+package build
+
+import mill._, javalib._, publish._
+
+import mill.scalalib.SonatypeCentralPublishModule
+
+object foo extends JavaModule with SonatypeCentralPublishModule {
+  def scalaVersion = "2.13.8"
+  def publishVersion = "0.0.1"
+
+  def pomSettings = PomSettings(
+    description = "Hello",
+    organization = "com.lihaoyi",
+    url = "https://github.com/lihaoyi/example",
+    licenses = Seq(License.MIT),
+    versionControl = VersionControl.github("lihaoyi", "example"),
+    developers = Seq(Developer("lihaoyi", "Li Haoyi", "https://github.com/lihaoyi"))
+  )
+}

example/javalib/publishing/9-publish-module-sonatype/build.mill

@@ -0,0 +1,7 @@
+package foo;
+
+public class Foo {
+  public static void main(String[] args) {
+    System.out.println("Hello World");
+  }
+}

example/javalib/publishing/9-publish-module-sonatype/foo/src/foo/Foo.java

@@ -0,0 +1,20 @@
+//// SNIPPET:BUILD
+package build
+
+import mill._, kotlinlib._, publish._
+
+import mill.scalalib.SonatypeCentralPublishModule
+
+object foo extends KotlinModule with SonatypeCentralPublishModule {
+  def scalaVersion = "2.13.8"
+  def publishVersion = "0.0.1"
+
+  def pomSettings = PomSettings(
+    description = "Hello",
+    organization = "com.lihaoyi",
+    url = "https://github.com/lihaoyi/example",
+    licenses = Seq(License.MIT),
+    versionControl = VersionControl.github("lihaoyi", "example"),
+    developers = Seq(Developer("lihaoyi", "Li Haoyi", "https://github.com/lihaoyi"))
+  )
+}

example/kotlinlib/publishing/3-publish-module-sonatype/build.mill

@@ -0,0 +1,3 @@
+package foo
+
+fun main(args: Array<String>) = println("Hello World")

example/kotlinlib/publishing/3-publish-module-sonatype/foo/src/foo/Foo.kt

@@ -0,0 +1,17 @@
+//// SNIPPET:BUILD
+package build
+import mill._, scalalib._, publish._
+
+object foo extends ScalaModule with SonatypeCentralPublishModule {
+  def scalaVersion = "2.13.8"
+  def publishVersion = "0.0.1"
+
+  def pomSettings = PomSettings(
+    description = "Hello",
+    organization = "com.lihaoyi",
+    url = "https://github.com/lihaoyi/example",
+    licenses = Seq(License.MIT),
+    versionControl = VersionControl.github("lihaoyi", "example"),
+    developers = Seq(Developer("lihaoyi", "Li Haoyi", "https://github.com/lihaoyi"))
+  )
+}

example/scalalib/publishing/3-publish-module-sonatype/build.mill

@@ -0,0 +1,6 @@
+package foo
+object Foo {
+  def main(args: Array[String]): Unit = {
+    println("Hello World")
+  }
+}

example/scalalib/publishing/3-publish-module-sonatype/foo/src/Foo.scala

@@ -9,6 +9,5 @@
         <orderEntry type="inheritedJdk"/>
         <orderEntry type="sourceFolder" forTests="false"/>
         <orderEntry type="library" name="scala-SDK-2.13.<!-- IGNORE -->" level="project"/>
-<!-- IGNORE -->
     </component>
 </module>

integration/ide/gen-idea/resources/hello-idea/idea/mill_modules/mill-build.iml

@@ -5,7 +5,11 @@ import mill.contrib.buildinfo.BuildInfo
 import scala.util.chaining._
 object `package` extends RootModule with build.MillStableScalaModule {
   def moduleDeps = Seq(build.main, build.scalalib.api, build.testrunner)
-  def ivyDeps = Agg(build.Deps.scalafmtDynamic, build.Deps.scalaXml)
+  def ivyDeps = Agg(
+    build.Deps.scalafmtDynamic,
+    build.Deps.scalaXml,
+    build.Deps.sonatypeCentralClient
+  )
   def testIvyDeps = super.testIvyDeps() ++ Agg(build.Deps.TestDeps.scalaCheck)
   def testTransitiveDeps =
     super.testTransitiveDeps() ++ Seq(worker.testDep(), `classgraph-worker`.testDep())

scalalib/package.mill

@@ -1,11 +1,13 @@
-package mill.contrib.sonatypecentral
+package mill.scalalib
 
 import com.lumidion.sonatype.central.client.core.{PublishingType, SonatypeCredentials}
 import mill._
 import scalalib._
 import define.{ExternalModule, Task}
-import mill.api.Result
-import mill.contrib.sonatypecentral.SonatypeCentralPublishModule.{
+import mill.main.Tasks
+import mill.define.TaskModule
+import mill.api.{Result, experimental}
+import mill.scalalib.SonatypeCentralPublishModule.{
   defaultAwaitTimeout,
   defaultConnectTimeout,
   defaultCredentials,
@@ -19,6 +21,7 @@ import mill.scalalib.publish.SonatypeHelpers.{
   USERNAME_ENV_VARIABLE_NAME
 }
 
+@experimental
 trait SonatypeCentralPublishModule extends PublishModule {
   def sonatypeCentralGpgArgs: T[String] = Task {
     PublishModule.defaultGpgArgsForPassphrase(Task.env.get("MILL_PGP_PASSPHRASE")).mkString(",")
@@ -60,16 +63,20 @@ trait SonatypeCentralPublishModule extends PublishModule {
     }
 }
 
-object SonatypeCentralPublishModule extends ExternalModule {
+object SonatypeCentralPublishModule extends ExternalModule with TaskModule {
 
   val defaultCredentials: String = ""
   val defaultReadTimeout: Int = 60000
   val defaultConnectTimeout: Int = 5000
   val defaultAwaitTimeout: Int = 120 * 1000
   val defaultShouldRelease: Boolean = true
 
+  // Set the default command to "publishAll"
+  def defaultCommandName(): String = "publishAll"
+
   def publishAll(
-      publishArtifacts: mill.main.Tasks[PublishModule.PublishData],
+      publishArtifacts: Tasks[PublishModule.PublishData] =
+        Tasks.resolveMainDefault("__.publishArtifacts"),
       username: String = defaultCredentials,
       password: String = defaultCredentials,
       shouldRelease: Boolean = defaultShouldRelease,

contrib/sonatypecentral/src/mill/contrib/sonatypecentral/SonatypeCentralPublishModule.scala renamed to scalalib/src/mill/scalalib/SonatypeCentralPublishModule.scala

@@ -1,4 +1,4 @@
-package mill.contrib.sonatypecentral
+package mill.scalalib
 
 import com.lumidion.sonatype.central.client.core.{
   DeploymentName,