Document publish task stubs in included builds

build.gradle.kts

@@ -3,5 +3,6 @@ plugins {
 }
 
 rootProjectConvention {
+    // Add `publishAll` and `publish` tasks that delegate to the subprojects and included builds.
     registerPublishTasks.set(true)
 }

docs/content/conventions/rootproject.md

@@ -22,3 +22,24 @@ rootProjectConvention {
     registerStubPublishTasks.set(false)
 }
 ```
+
+
+## Publish Tasks
+By default, the Root Project convention plugin only creates lifecycle tasks (`build`, `assemble`, `clean`, `check`, and their corresponding versions with the `All` suffix), but no tasks for publishing.  The reasoning is that not all subprojects and included builds will be configured to be published, and as such, delegating `publish` to these included builds can cause errors. However, if you _do_ want root-level `publish` and `publishToMavenLocal` tasks (and `publishAll` and `publishAllToMavenLocal`), then you can achieve this by setting `registerPublishTasks` to `true` in the root project:
+
+```kotlin title="build.gradle.kts"
+rootProjectConvention {
+    registerPublishTasks.set(true)
+}
+```
+
+!!! warning ""
+    This assumes that all included builds have `publish` and `publishToMavenLocal` tasks. This is generally not the case, as not all included builds may have the `maven-publish` plugin applied. In contrast, for subprojects this is already handled correctly by this plugin.
+
+For included builds that will not be published, we have to add _stub_ `publish` and `publishToMavenLocal` tasks. These tasks will do nothing, but will prevent errors when the root project tries to delegate these tasks to the included builds. To add these stub tasks, set `registerStubPublishTasks` to `true` in the included build's root project:
+
+```kotlin title="build.gradle.kts"
+rootProjectConvention {
+    registerStubPublishTasks.set(true)
+}
+```

example/build.gradle.kts

@@ -16,5 +16,7 @@ allprojects {
 
 
 rootProjectConvention {
+    // Just register some stub `publish` and `publishToMavenLocal` tasks,
+    //  so we can call `publish` on all included builds from the root without issues.
     registerStubPublishTasks.set(true)
 }

example/settings.gradle.kts

@@ -1,5 +1,3 @@
-import org.metaborg.convention.MavenPublishConventionExtension
-
 rootProject.name = "example-project"
 
 pluginManagement {