From 976631e4744bfe1a2497a2a3d4944fce745b81f0 Mon Sep 17 00:00:00 2001
From: Andrew Purtell <apurtell@apache.org>
Date: Tue, 5 May 2026 13:33:19 -0700
Subject: [PATCH 1/3] PHOENIX-7842 Reduce the shading contribution to build
 time

---
 BUILDING.md                                   | 19 +++++
 phoenix-assembly/pom.xml                      | 78 +++++++++++++------
 .../src/build/components/all-common-jars.xml  | 10 +--
 .../src/build/components/assembly-noop.xml    | 28 +++++++
 .../build/components/release-only-jars.xml    | 40 ++++++++++
 .../src/build/package-to-tar-all.xml          |  3 +
 .../phoenix-client-embedded/pom.xml           |  4 +-
 .../phoenix-client-lite/pom.xml               |  4 +-
 phoenix-mapreduce-byo-shaded-hbase/pom.xml    |  4 +-
 phoenix-server/pom.xml                        |  4 +-
 pom.xml                                       | 18 ++++-
 11 files changed, 170 insertions(+), 42 deletions(-)
 create mode 100644 phoenix-assembly/src/build/components/assembly-noop.xml
 create mode 100644 phoenix-assembly/src/build/components/release-only-jars.xml

diff --git a/BUILDING.md b/BUILDING.md
index 1ba283819ac..f0ef044a579 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -69,6 +69,25 @@ and optionally, to just skip all the tests and build the jars:
 
 Note: javadocs are generated in target/apidocs
 
+Faster builds
+-------------
+
+The following options can dramatically reduce wall-clock time:
+
+* The four shade modules are reactor-siblings and the shade plugin is thread-safe, so they can build concurrently:
+
+  `$ mvn -T 1C clean package -DskipTests`
+
+  (`-T 1C` uses one build thread per CPU core. `-T 4` is also fine.)
+
+* Skip the shaded artifacts and assembly when you are iterating on `phoenix-core*` and do not need the shaded uberjars or the binary tarball. Pass `-DPhoenixPatchProcess` to deactivate the `shade-and-assembly` profile entirely (this is what the ASF Yetus precommit and the Jenkinsfile use):
+
+  `$ mvn package -DskipTests -DPhoenixPatchProcess`
+
+* By default the shade executions do not also re-shade the dependency source artifacts. The `release` profile re-enables it for RC / publish builds. To force it on outside of `-Prelease`, pass `-DshadeSources=true`.
+
+* The `phoenix-mapreduce-byo-shaded-hbase` module is built only under `-Prelease`, which bundles its uberjar into the release binary tarball.
+
 HBase version compatibility
 ---------------------------
 
diff --git a/phoenix-assembly/pom.xml b/phoenix-assembly/pom.xml
index ae52be7d23e..30e374ee1ae 100644
--- a/phoenix-assembly/pom.xml
+++ b/phoenix-assembly/pom.xml
@@ -32,6 +32,11 @@
     <source.skip>true</source.skip>
     <jacocoArgLine/>
     <main.basedir>${project.parent.basedir}</main.basedir>
+    <!-- Selects the (otherwise unused) component descriptor referenced by
+         src/build/package-to-tar-all.xml. Default = no-op. The release
+         profile overrides this to add the byo-shaded-hbase mapreduce uberjar
+         to the binary tarball. -->
+    <assembly.mapreduce.componentDescriptor>src/build/components/assembly-noop.xml</assembly.mapreduce.componentDescriptor>
   </properties>
 
   <dependencies>
@@ -40,10 +45,8 @@
       <groupId>org.apache.phoenix</groupId>
       <artifactId>phoenix-server-${hbase.suffix}</artifactId>
     </dependency>
-    <dependency>
-      <groupId>org.apache.phoenix</groupId>
-      <artifactId>phoenix-mapreduce-byo-shaded-hbase-${hbase.suffix}</artifactId>
-    </dependency>
+    <!-- phoenix-mapreduce-byo-shaded-hbase-${hbase.suffix} is added under
+         the `release` profile, since it is built only for releases. -->
     <dependency>
       <groupId>org.apache.phoenix</groupId>
       <artifactId>phoenix-client-embedded-${hbase.suffix}</artifactId>
@@ -139,25 +142,9 @@
               </arguments>
             </configuration>
           </execution>
-          <execution>
-            <id>mapreduce without version</id>
-            <goals>
-              <goal>exec</goal>
-            </goals>
-            <phase>compile</phase>
-            <configuration>
-              <executable>ln</executable>
-              <workingDirectory>${project.basedir}/../phoenix-mapreduce-byo-shaded-hbase/target</workingDirectory>
-              <arguments>
-                <argument>-fnsv</argument>
-                <argument>phoenix-mapreduce-byo-shaded-hbase-${hbase.suffix}-${project.version}.jar</argument>
-                <argument>
-                  <!-- We are overwriting the unshaded  JAR, but we don't care -->
-                  phoenix-mapreduce-byo-shaded-hbase-${hbase.suffix}.jar
-                </argument>
-              </arguments>
-            </configuration>
-          </execution>
+          <!-- The mapreduce-byo-shaded-hbase exec execution lives in the
+               `release` profile below, since the byo-shaded-hbase mapreduce
+               uberjar is only built for releases. -->
           <execution>
             <id>pherf without version</id>
             <goals>
@@ -214,6 +201,51 @@
   </build>
 
   <profiles>
+    <profile>
+      <!-- Release-only artifacts. The byo-shaded-hbase mapreduce uberjar is
+           expensive to shade and is not needed for normal dev builds, so it
+           is built only when -Prelease is active (see root pom.xml). This
+           profile wires the resulting jar into the binary tarball. -->
+      <id>release</id>
+      <properties>
+        <assembly.mapreduce.componentDescriptor>src/build/components/release-only-jars.xml</assembly.mapreduce.componentDescriptor>
+      </properties>
+      <dependencies>
+        <dependency>
+          <groupId>org.apache.phoenix</groupId>
+          <artifactId>phoenix-mapreduce-byo-shaded-hbase-${hbase.suffix}</artifactId>
+        </dependency>
+      </dependencies>
+      <build>
+        <plugins>
+          <plugin>
+            <groupId>org.codehaus.mojo</groupId>
+            <artifactId>exec-maven-plugin</artifactId>
+            <executions>
+              <execution>
+                <id>mapreduce-byo-shaded-hbase</id>
+                <goals>
+                  <goal>exec</goal>
+                </goals>
+                <phase>compile</phase>
+                <configuration>
+                  <executable>ln</executable>
+                  <workingDirectory>${project.basedir}/../phoenix-mapreduce-byo-shaded-hbase/target</workingDirectory>
+                  <arguments>
+                    <argument>-fnsv</argument>
+                    <argument>phoenix-mapreduce-byo-shaded-hbase-${hbase.suffix}-${project.version}.jar</argument>
+                    <argument>
+                      <!-- We are overwriting the unshaded JAR, but we don't care -->
+                      phoenix-mapreduce-byo-shaded-hbase-${hbase.suffix}.jar
+                    </argument>
+                  </arguments>
+                </configuration>
+              </execution>
+            </executions>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
     <profile>
       <id>coverage</id>
       <dependencies>
diff --git a/phoenix-assembly/src/build/components/all-common-jars.xml b/phoenix-assembly/src/build/components/all-common-jars.xml
index c2f943fc392..3b9dd4808f3 100644
--- a/phoenix-assembly/src/build/components/all-common-jars.xml
+++ b/phoenix-assembly/src/build/components/all-common-jars.xml
@@ -47,14 +47,8 @@
         <include>phoenix-server-${hbase.suffix}.jar</include>
       </includes>
     </fileSet>
-    <fileSet>
-      <directory>${project.basedir}/../phoenix-mapreduce-byo-shaded-hbase/target</directory>
-      <outputDirectory>/</outputDirectory>
-      <includes>
-        <include>phoenix-mapreduce-byo-shaded-hbase-${hbase.suffix}-${project.version}.jar</include>
-        <include>phoenix-mapreduce-byo-shaded-hbase-${hbase.suffix}.jar</include>
-      </includes>
-    </fileSet>
+    <!-- The byo-shaded-hbase mapreduce uberjar is added only under -Prelease via
+         components/release-only-jars.xml (see phoenix-assembly/pom.xml). -->
     <fileSet>
       <directory>${project.basedir}/../phoenix-pherf/target</directory>
       <outputDirectory>/</outputDirectory>
diff --git a/phoenix-assembly/src/build/components/assembly-noop.xml b/phoenix-assembly/src/build/components/assembly-noop.xml
new file mode 100644
index 00000000000..dbfcf6ddd7e
--- /dev/null
+++ b/phoenix-assembly/src/build/components/assembly-noop.xml
@@ -0,0 +1,28 @@
+<?xml version='1.0'?>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+<!--
+  Empty placeholder component descriptor used in default builds where the
+  release-only jars (mapreduce byo-shaded-hbase) are not produced.
+  Selected by the `assembly.mapreduce.componentDescriptor` property
+  defined in phoenix-assembly/pom.xml.
+-->
+<component/>
diff --git a/phoenix-assembly/src/build/components/release-only-jars.xml b/phoenix-assembly/src/build/components/release-only-jars.xml
new file mode 100644
index 00000000000..0b5917b3b70
--- /dev/null
+++ b/phoenix-assembly/src/build/components/release-only-jars.xml
@@ -0,0 +1,40 @@
+<?xml version='1.0'?>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+<!--
+  Component descriptor wired in only under the release profile.
+  Adds the byo-shaded-hbase mapreduce uberjar to the binary tarball.
+  In default (non-release) builds this descriptor is replaced with the
+  no-op `assembly-noop.xml` via the `assembly.mapreduce.componentDescriptor`
+  property defined in phoenix-assembly/pom.xml.
+-->
+<component>
+  <fileSets>
+    <fileSet>
+      <directory>${project.basedir}/../phoenix-mapreduce-byo-shaded-hbase/target</directory>
+      <outputDirectory>/</outputDirectory>
+      <includes>
+        <include>phoenix-mapreduce-byo-shaded-hbase-${hbase.suffix}-${project.version}.jar</include>
+        <include>phoenix-mapreduce-byo-shaded-hbase-${hbase.suffix}.jar</include>
+      </includes>
+    </fileSet>
+  </fileSets>
+</component>
diff --git a/phoenix-assembly/src/build/package-to-tar-all.xml b/phoenix-assembly/src/build/package-to-tar-all.xml
index 9dd292842a2..93c9191dd1d 100644
--- a/phoenix-assembly/src/build/package-to-tar-all.xml
+++ b/phoenix-assembly/src/build/package-to-tar-all.xml
@@ -35,5 +35,8 @@
     <componentDescriptor>src/build/components/all-common-jars.xml</componentDescriptor>
     <componentDescriptor>src/build/components/all-common-files.xml</componentDescriptor>
     <componentDescriptor>src/build/components/all-common-dependencies.xml</componentDescriptor>
+    <!-- Resolves to assembly-noop.xml in default builds and
+         release-only-jars.xml under -Prelease. See phoenix-assembly/pom.xml. -->
+    <componentDescriptor>${assembly.mapreduce.componentDescriptor}</componentDescriptor>
   </componentDescriptors>
 </assembly>
diff --git a/phoenix-client-parent/phoenix-client-embedded/pom.xml b/phoenix-client-parent/phoenix-client-embedded/pom.xml
index f7a674e5342..2c68efee4ce 100644
--- a/phoenix-client-parent/phoenix-client-embedded/pom.xml
+++ b/phoenix-client-parent/phoenix-client-embedded/pom.xml
@@ -116,10 +116,10 @@
             </goals>
             <phase>package</phase>
             <configuration>
-              <promoteTransitiveDependencies>true</promoteTransitiveDependencies>
               <shadeTestJar>false</shadeTestJar>
               <createSourcesJar>${shadeSources}</createSourcesJar>
-              <dependencyReducedPomLocation>${basedir}/target/pom.xml</dependencyReducedPomLocation>
+              <!-- Nothing consumes a dep-reduced POM for this uberjar. -->
+              <createDependencyReducedPom>false</createDependencyReducedPom>
               <artifactSet>
                 <includes>
                   <include>*:*</include>
diff --git a/phoenix-client-parent/phoenix-client-lite/pom.xml b/phoenix-client-parent/phoenix-client-lite/pom.xml
index e915fbef017..7e4f523baf5 100644
--- a/phoenix-client-parent/phoenix-client-lite/pom.xml
+++ b/phoenix-client-parent/phoenix-client-lite/pom.xml
@@ -116,10 +116,10 @@
             </goals>
             <phase>package</phase>
             <configuration>
-              <promoteTransitiveDependencies>true</promoteTransitiveDependencies>
               <shadeTestJar>false</shadeTestJar>
               <createSourcesJar>${shadeSources}</createSourcesJar>
-              <dependencyReducedPomLocation>${basedir}/target/pom.xml</dependencyReducedPomLocation>
+              <!-- Nothing consumes a dep-reduced POM for this uberjar. -->
+              <createDependencyReducedPom>false</createDependencyReducedPom>
               <artifactSet>
                 <includes>
                   <include>*:*</include>
diff --git a/phoenix-mapreduce-byo-shaded-hbase/pom.xml b/phoenix-mapreduce-byo-shaded-hbase/pom.xml
index 477cd063451..07133d59e9c 100644
--- a/phoenix-mapreduce-byo-shaded-hbase/pom.xml
+++ b/phoenix-mapreduce-byo-shaded-hbase/pom.xml
@@ -583,10 +583,10 @@
             </goals>
             <phase>package</phase>
             <configuration>
-              <promoteTransitiveDependencies>true</promoteTransitiveDependencies>
               <shadeTestJar>false</shadeTestJar>
               <createSourcesJar>${shadeSources}</createSourcesJar>
-              <dependencyReducedPomLocation>${basedir}/target/pom.xml</dependencyReducedPomLocation>
+              <!-- Nothing consumes a dep-reduced POM for this uberjar. -->
+              <createDependencyReducedPom>false</createDependencyReducedPom>
               <artifactSet>
                 <includes>
                   <include>*:*</include>
diff --git a/phoenix-server/pom.xml b/phoenix-server/pom.xml
index 05e068f108e..bc1808e9d75 100644
--- a/phoenix-server/pom.xml
+++ b/phoenix-server/pom.xml
@@ -550,10 +550,10 @@
             </goals>
             <phase>package</phase>
             <configuration>
-              <promoteTransitiveDependencies>true</promoteTransitiveDependencies>
               <shadeTestJar>false</shadeTestJar>
               <createSourcesJar>${shadeSources}</createSourcesJar>
-              <dependencyReducedPomLocation>${basedir}/target/pom.xml</dependencyReducedPomLocation>
+              <!-- Nothing consumes a dep-reduced POM for this uberjar. -->
+              <createDependencyReducedPom>false</createDependencyReducedPom>
               <artifactSet>
                 <includes>
                   <include>*:*</include>
diff --git a/pom.xml b/pom.xml
index 9eb87cd31ed..5fccc53ba53 100644
--- a/pom.xml
+++ b/pom.xml
@@ -92,7 +92,10 @@
     <test.output.tofile>true</test.output.tofile>
     <top.dir>${project.basedir}/..</top.dir>
     <test.tmp.dir>${project.build.directory}</test.tmp.dir>
-    <shadeSources>true</shadeSources>
+    <!-- Sources-jar shading roughly doubles the time of every shade execution.
+         Default it OFF here; the `release` profile re-enables it so RC / publish
+         builds still produce shaded sources jars. -->
+    <shadeSources>false</shadeSources>
 
     <!-- Dependency versions -->
     <jackson-bom.version>2.18.4.1</jackson-bom.version>
@@ -161,7 +164,7 @@
     <lifecycle-mapping.version>1.0.0</lifecycle-mapping.version>
     <maven-bundle-plugin.version>5.1.9</maven-bundle-plugin.version>
     <exec-maven-plugin.version>3.1.1</exec-maven-plugin.version>
-    <maven-shade-plugin.version>3.6.0</maven-shade-plugin.version>
+    <maven-shade-plugin.version>3.6.2</maven-shade-plugin.version>
     <!-- This overrides the property in the ASF parent project-->
     <version.maven-site-plugin>3.21.0</version.maven-site-plugin>
     <spotless.version>2.30.0</spotless.version>
@@ -2092,13 +2095,22 @@
         <module>phoenix-client-parent/phoenix-client-embedded</module>
         <module>phoenix-client-parent/phoenix-client-lite</module>
         <module>phoenix-server</module>
-        <module>phoenix-mapreduce-byo-shaded-hbase</module>
         <module>phoenix-assembly</module>
       </modules>
     </profile>
     <!-- this profile should be activated for release builds -->
     <profile>
       <id>release</id>
+      <!-- The byo-shaded-hbase mapreduce uberjar is a release-only artifact.
+           It costs several minutes to shade and is not needed for normal
+           dev builds, so we only add it to the reactor under -Prelease. -->
+      <modules>
+        <module>phoenix-mapreduce-byo-shaded-hbase</module>
+      </modules>
+      <properties>
+        <!-- Re-enable shaded sources jars for RC / publish builds. -->
+        <shadeSources>true</shadeSources>
+      </properties>
       <build>
         <plugins>
           <plugin>

From 7f3cfb6a8d6546120d3657b98a61f42020de6984 Mon Sep 17 00:00:00 2001
From: Andrew Purtell <apurtell@apache.org>
Date: Tue, 5 May 2026 16:04:18 -0700
Subject: [PATCH 2/3] Leave createDependencyReducedPom and
 promoteTransitiveDependencies alone.

They don't contribute significantly to build time.
---
 phoenix-client-parent/phoenix-client-embedded/pom.xml | 4 ++--
 phoenix-client-parent/phoenix-client-lite/pom.xml     | 4 ++--
 phoenix-mapreduce-byo-shaded-hbase/pom.xml            | 4 ++--
 phoenix-server/pom.xml                                | 4 ++--
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/phoenix-client-parent/phoenix-client-embedded/pom.xml b/phoenix-client-parent/phoenix-client-embedded/pom.xml
index 2c68efee4ce..f7a674e5342 100644
--- a/phoenix-client-parent/phoenix-client-embedded/pom.xml
+++ b/phoenix-client-parent/phoenix-client-embedded/pom.xml
@@ -116,10 +116,10 @@
             </goals>
             <phase>package</phase>
             <configuration>
+              <promoteTransitiveDependencies>true</promoteTransitiveDependencies>
               <shadeTestJar>false</shadeTestJar>
               <createSourcesJar>${shadeSources}</createSourcesJar>
-              <!-- Nothing consumes a dep-reduced POM for this uberjar. -->
-              <createDependencyReducedPom>false</createDependencyReducedPom>
+              <dependencyReducedPomLocation>${basedir}/target/pom.xml</dependencyReducedPomLocation>
               <artifactSet>
                 <includes>
                   <include>*:*</include>
diff --git a/phoenix-client-parent/phoenix-client-lite/pom.xml b/phoenix-client-parent/phoenix-client-lite/pom.xml
index 7e4f523baf5..e915fbef017 100644
--- a/phoenix-client-parent/phoenix-client-lite/pom.xml
+++ b/phoenix-client-parent/phoenix-client-lite/pom.xml
@@ -116,10 +116,10 @@
             </goals>
             <phase>package</phase>
             <configuration>
+              <promoteTransitiveDependencies>true</promoteTransitiveDependencies>
               <shadeTestJar>false</shadeTestJar>
               <createSourcesJar>${shadeSources}</createSourcesJar>
-              <!-- Nothing consumes a dep-reduced POM for this uberjar. -->
-              <createDependencyReducedPom>false</createDependencyReducedPom>
+              <dependencyReducedPomLocation>${basedir}/target/pom.xml</dependencyReducedPomLocation>
               <artifactSet>
                 <includes>
                   <include>*:*</include>
diff --git a/phoenix-mapreduce-byo-shaded-hbase/pom.xml b/phoenix-mapreduce-byo-shaded-hbase/pom.xml
index 07133d59e9c..477cd063451 100644
--- a/phoenix-mapreduce-byo-shaded-hbase/pom.xml
+++ b/phoenix-mapreduce-byo-shaded-hbase/pom.xml
@@ -583,10 +583,10 @@
             </goals>
             <phase>package</phase>
             <configuration>
+              <promoteTransitiveDependencies>true</promoteTransitiveDependencies>
               <shadeTestJar>false</shadeTestJar>
               <createSourcesJar>${shadeSources}</createSourcesJar>
-              <!-- Nothing consumes a dep-reduced POM for this uberjar. -->
-              <createDependencyReducedPom>false</createDependencyReducedPom>
+              <dependencyReducedPomLocation>${basedir}/target/pom.xml</dependencyReducedPomLocation>
               <artifactSet>
                 <includes>
                   <include>*:*</include>
diff --git a/phoenix-server/pom.xml b/phoenix-server/pom.xml
index bc1808e9d75..05e068f108e 100644
--- a/phoenix-server/pom.xml
+++ b/phoenix-server/pom.xml
@@ -550,10 +550,10 @@
             </goals>
             <phase>package</phase>
             <configuration>
+              <promoteTransitiveDependencies>true</promoteTransitiveDependencies>
               <shadeTestJar>false</shadeTestJar>
               <createSourcesJar>${shadeSources}</createSourcesJar>
-              <!-- Nothing consumes a dep-reduced POM for this uberjar. -->
-              <createDependencyReducedPom>false</createDependencyReducedPom>
+              <dependencyReducedPomLocation>${basedir}/target/pom.xml</dependencyReducedPomLocation>
               <artifactSet>
                 <includes>
                   <include>*:*</include>

From 1a5c2f9995633dd107a1a31bd70e4d5ad76992fd Mon Sep 17 00:00:00 2001
From: Andrew Purtell <apurtell@apache.org>
Date: Tue, 5 May 2026 16:17:28 -0700
Subject: [PATCH 3/3] Apply recommended updates from automated review

---
 BUILDING.md                                   | 24 +++++++++++++++----
 phoenix-assembly/pom.xml                      | 10 ++++----
 .../src/build/components/assembly-noop.xml    |  3 +++
 3 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/BUILDING.md b/BUILDING.md
index f0ef044a579..a09d9889772 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -69,24 +69,38 @@ and optionally, to just skip all the tests and build the jars:
 
 Note: javadocs are generated in target/apidocs
 
+Note: by default `mvn package` does not build `phoenix-mapreduce-byo-shaded-hbase`,
+and the resulting binary tarball does not contain its uberjar. RC / publish builds
+should use `-Prelease`, which adds that module back to the reactor and bundles its
+uberjar into the tarball. See "Faster builds" below.
+
 Faster builds
 -------------
 
 The following options can dramatically reduce wall-clock time:
 
-* The four shade modules are reactor-siblings and the shade plugin is thread-safe, so they can build concurrently:
+* `phoenix-mapreduce-byo-shaded-hbase` is the most expensive shade in the project
+  and is only needed for releases, so it is built only under `-Prelease`. A normal
+  `mvn package` skips it, and the binary tarball does not contain its uberjar.
+  Pass `-Prelease` to restore the previous behavior (this is what the ASF release
+  build does).
+
+* The shade modules are reactor-siblings and the shade plugin is thread-safe, so
+  they build concurrently with parallel reactor builds:
 
   `$ mvn -T 1C clean package -DskipTests`
 
   (`-T 1C` uses one build thread per CPU core. `-T 4` is also fine.)
 
-* Skip the shaded artifacts and assembly when you are iterating on `phoenix-core*` and do not need the shaded uberjars or the binary tarball. Pass `-DPhoenixPatchProcess` to deactivate the `shade-and-assembly` profile entirely (this is what the ASF Yetus precommit and the Jenkinsfile use):
+* Skip the shaded artifacts and assembly entirely when you are iterating on
+  `phoenix-core*` and do not need the shaded uberjars or the binary tarball.
+  Pass `-DPhoenixPatchProcess` to deactivate the `shade-and-assembly` profile
+  (this is what the ASF Yetus precommit and the Jenkinsfile use):
 
   `$ mvn package -DskipTests -DPhoenixPatchProcess`
 
-* By default the shade executions do not also re-shade the dependency source artifacts. The `release` profile re-enables it for RC / publish builds. To force it on outside of `-Prelease`, pass `-DshadeSources=true`.
-
-* The `phoenix-mapreduce-byo-shaded-hbase` module is built only under `-Prelease`, which bundles its uberjar into the release binary tarball.
+* Shaded sources jars are off by default. `-Prelease` (or `-DshadeSources=true`)
+  re-enables them; RC / publish builds get them automatically.
 
 HBase version compatibility
 ---------------------------
diff --git a/phoenix-assembly/pom.xml b/phoenix-assembly/pom.xml
index 30e374ee1ae..d9b97188a95 100644
--- a/phoenix-assembly/pom.xml
+++ b/phoenix-assembly/pom.xml
@@ -45,8 +45,9 @@
       <groupId>org.apache.phoenix</groupId>
       <artifactId>phoenix-server-${hbase.suffix}</artifactId>
     </dependency>
-    <!-- phoenix-mapreduce-byo-shaded-hbase-${hbase.suffix} is added under
-         the `release` profile, since it is built only for releases. -->
+    <!-- See the `release` profile below for
+         phoenix-mapreduce-byo-shaded-hbase-${hbase.suffix}. It is built only for
+         releases. -->
     <dependency>
       <groupId>org.apache.phoenix</groupId>
       <artifactId>phoenix-client-embedded-${hbase.suffix}</artifactId>
@@ -142,9 +143,8 @@
               </arguments>
             </configuration>
           </execution>
-          <!-- The mapreduce-byo-shaded-hbase exec execution lives in the
-               `release` profile below, since the byo-shaded-hbase mapreduce
-               uberjar is only built for releases. -->
+          <!-- See the `release` profile below for the mapreduce-byo-shaded-hbase
+               symlink exec. That uberjar is only built for releases. -->
           <execution>
             <id>pherf without version</id>
             <goals>
diff --git a/phoenix-assembly/src/build/components/assembly-noop.xml b/phoenix-assembly/src/build/components/assembly-noop.xml
index dbfcf6ddd7e..2c5f05fc92b 100644
--- a/phoenix-assembly/src/build/components/assembly-noop.xml
+++ b/phoenix-assembly/src/build/components/assembly-noop.xml
@@ -24,5 +24,8 @@
   release-only jars (mapreduce byo-shaded-hbase) are not produced.
   Selected by the `assembly.mapreduce.componentDescriptor` property
   defined in phoenix-assembly/pom.xml.
+
+  An empty `<component/>` is a valid component descriptor per the assembly
+  plugin schema. Every child of <component> is optional.
 -->
 <component/>