This is an automated email from the ASF dual-hosted git repository.
epugh pushed a commit to branch branch_9x
in repository https://gitbox.apache.org/repos/asf/solr.git
The following commit(s) were added to refs/heads/branch_9x by this push:
new 95c3de5eb3f Migrate gradle help files into a subdir of dev-docs for
findability (#3685)
95c3de5eb3f is described below
commit 95c3de5eb3f4e5e32989a6a921839e90c16c12fe
Author: Eric Pugh <[email protected]>
AuthorDate: Wed Oct 1 07:42:21 2025 -0400
Migrate gradle help files into a subdir of dev-docs for findability (#3685)
"gradlew help used to be our ONLY source of developer docs. Today we have
a set of docs in ./dev-docs/ that developers reference. By relocating the
./help/*.txt doc files into the ./dev-docs/ directory, we increase the change
of findablity, while still preserving the "gradlew help" command.
---
dev-docs/gradle-help/README.md | 24 ++++++++++++++++++++++
{help => dev-docs/gradle-help}/ant.txt | 0
{help => dev-docs/gradle-help}/dependencies.txt | 0
.../gradle-help/docker.txt | 0
{help => dev-docs/gradle-help}/forbiddenApis.txt | 0
{help => dev-docs/gradle-help}/formatting.txt | 0
{help => dev-docs/gradle-help}/git.txt | 0
{help => dev-docs/gradle-help}/localSettings.txt | 0
{help => dev-docs/gradle-help}/publishing.txt | 0
{help => dev-docs/gradle-help}/tests.txt | 0
.../gradle-help}/validateLogCalls.txt | 0
{help => dev-docs/gradle-help}/workflow.txt | 0
dev-docs/lucene-upgrade.md | 2 +-
dev-tools/scripts/releaseWizard.yaml | 4 ++--
gradle/help.gradle | 22 ++++++++++----------
gradle/validation/spotless.gradle | 2 +-
solr/docker/build.gradle | 2 +-
17 files changed, 40 insertions(+), 16 deletions(-)
diff --git a/dev-docs/gradle-help/README.md b/dev-docs/gradle-help/README.md
new file mode 100644
index 00000000000..58df221401d
--- /dev/null
+++ b/dev-docs/gradle-help/README.md
@@ -0,0 +1,24 @@
+<!--
+ 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.
+-->
+
+# Gradle Help Documentation
+
+This directory contains text files that provide help documentation for various
Gradle tasks and project workflows in Solr.
+
+## Purpose
+
+These text files serve as the content for Gradle's help tasks. When users run
commands like `./gradlew helpWorkflow` or `./gradlew helpTests`, Gradle
displays the content of the corresponding text file in this directory.
diff --git a/help/ant.txt b/dev-docs/gradle-help/ant.txt
similarity index 100%
rename from help/ant.txt
rename to dev-docs/gradle-help/ant.txt
diff --git a/help/dependencies.txt b/dev-docs/gradle-help/dependencies.txt
similarity index 100%
rename from help/dependencies.txt
rename to dev-docs/gradle-help/dependencies.txt
diff --git a/solr/docker/gradle-help.txt b/dev-docs/gradle-help/docker.txt
similarity index 100%
rename from solr/docker/gradle-help.txt
rename to dev-docs/gradle-help/docker.txt
diff --git a/help/forbiddenApis.txt b/dev-docs/gradle-help/forbiddenApis.txt
similarity index 100%
rename from help/forbiddenApis.txt
rename to dev-docs/gradle-help/forbiddenApis.txt
diff --git a/help/formatting.txt b/dev-docs/gradle-help/formatting.txt
similarity index 100%
rename from help/formatting.txt
rename to dev-docs/gradle-help/formatting.txt
diff --git a/help/git.txt b/dev-docs/gradle-help/git.txt
similarity index 100%
rename from help/git.txt
rename to dev-docs/gradle-help/git.txt
diff --git a/help/localSettings.txt b/dev-docs/gradle-help/localSettings.txt
similarity index 100%
rename from help/localSettings.txt
rename to dev-docs/gradle-help/localSettings.txt
diff --git a/help/publishing.txt b/dev-docs/gradle-help/publishing.txt
similarity index 100%
rename from help/publishing.txt
rename to dev-docs/gradle-help/publishing.txt
diff --git a/help/tests.txt b/dev-docs/gradle-help/tests.txt
similarity index 100%
rename from help/tests.txt
rename to dev-docs/gradle-help/tests.txt
diff --git a/help/validateLogCalls.txt
b/dev-docs/gradle-help/validateLogCalls.txt
similarity index 100%
rename from help/validateLogCalls.txt
rename to dev-docs/gradle-help/validateLogCalls.txt
diff --git a/help/workflow.txt b/dev-docs/gradle-help/workflow.txt
similarity index 100%
rename from help/workflow.txt
rename to dev-docs/gradle-help/workflow.txt
diff --git a/dev-docs/lucene-upgrade.md b/dev-docs/lucene-upgrade.md
index e5ab91e7c9f..21f6051f223 100644
--- a/dev-docs/lucene-upgrade.md
+++ b/dev-docs/lucene-upgrade.md
@@ -82,5 +82,5 @@ Push the local branch to github (fork) and open a pull
request.
## Looking for something else?
-Thanks for reading these upgrade steps! But perhaps you were looking for
information on trying out prerelease Lucene changes or joint local Solr and
Lucene development? If so then please see the 'Update Lucene prerelease' and
'Lucene local dependency substitution' sections in the
[help/dependencies.txt](../help/dependencies.txt) documentation.
+Thanks for reading these upgrade steps! But perhaps you were looking for
information on trying out prerelease Lucene changes or joint local Solr and
Lucene development? If so then please see the 'Update Lucene prerelease' and
'Lucene local dependency substitution' sections in the
[dev-docs/gradle-help/dependencies.txt](gradle-help/dependencies.txt)
documentation.
diff --git a/dev-tools/scripts/releaseWizard.yaml
b/dev-tools/scripts/releaseWizard.yaml
index 4f1f2c7e50f..840273dbbfb 100644
--- a/dev-tools/scripts/releaseWizard.yaml
+++ b/dev-tools/scripts/releaseWizard.yaml
@@ -257,7 +257,7 @@ groups:
fingerprint for the key.
You can choose between signing the release with the gpg program or with
the
- gradle signing plugin. Read about the difference in
https://github.com/apache/solr/blob/main/help/publishing.txt
+ gradle signing plugin. Read about the difference in
https://github.com/apache/solr/blob/main/dev-docs/gradle-help/publishing.txt
This wizard can prompt you securely for your passphrase (will not be
stored) and pass it on to
buildAndPushRelease in a secure way. However, you can also configure
your passphrase in advance
@@ -269,7 +269,7 @@ groups:
- https://infra.apache.org/openpgp.html#apache-wot
- https://id.apache.org
- https://dist.apache.org/repos/dist/release/solr/KEYS
- - https://github.com/apache/solr/blob/main/help/publishing.txt
+ -
https://github.com/apache/solr/blob/main/dev-docs/gradle-help/publishing.txt
- !Todo
id: jira_permissions
title: Obtain the necessary permissions for Apache Jira
diff --git a/gradle/help.gradle b/gradle/help.gradle
index b6b64f9a567..f17b4067efb 100644
--- a/gradle/help.gradle
+++ b/gradle/help.gradle
@@ -19,17 +19,17 @@
configure(rootProject) {
def helpFiles = [
- ["Workflow", "help/workflow.txt", "Typical workflow commands."],
- ["Ant", "help/ant.txt", "Ant-gradle migration help."],
- ["Tests", "help/tests.txt", "Tests, filtering, beasting, etc."],
- ["Formatting", "help/formatting.txt", "Code formatting conventions."],
- ["Deps", "help/dependencies.txt", "Declaring, inspecting and excluding
dependencies."],
- ["ForbiddenApis", "help/forbiddenApis.txt", "How to add/apply rules for
forbidden APIs."],
- ["LocalSettings", "help/localSettings.txt", "Local settings, overrides
and build performance tweaks."],
- ["Git", "help/git.txt", "Git assistance and guides."],
- ["ValidateLogCalls", "help/validateLogCalls.txt", "How to use logging
calls efficiently."],
- ["Publishing", "help/publishing.txt", "Release publishing publishing,
signing, etc."],
- ["Docker", "solr/docker/gradle-help.txt", "Building Solr Docker
images."],
+ ["Workflow", "dev-docs/gradle-help/workflow.txt", "Typical workflow
commands."],
+ ["Ant", "dev-docs/gradle-help/ant.txt", "Ant-gradle migration help."],
+ ["Tests", "dev-docs/gradle-help/tests.txt", "Tests, filtering, beasting,
etc."],
+ ["Formatting", "dev-docs/gradle-help/formatting.txt", "Code formatting
conventions."],
+ ["Deps", "dev-docs/gradle-help/dependencies.txt", "Declaring, inspecting
and excluding dependencies."],
+ ["ForbiddenApis", "dev-docs/gradle-help/forbiddenApis.txt", "How to
add/apply rules for forbidden APIs."],
+ ["LocalSettings", "dev-docs/gradle-help/localSettings.txt", "Local
settings, overrides and build performance tweaks."],
+ ["Git", "dev-docs/gradle-help/git.txt", "Git assistance and guides."],
+ ["ValidateLogCalls", "dev-docs/gradle-help/validateLogCalls.txt", "How
to use logging calls efficiently."],
+ ["Publishing", "dev-docs/gradle-help/publishing.txt", "Release
publishing publishing, signing, etc."],
+ ["Docker", "dev-docs/gradle-help/docker.txt", "Building Solr Docker
images."],
]
helpFiles.each { section, path, sectionInfo ->
diff --git a/gradle/validation/spotless.gradle
b/gradle/validation/spotless.gradle
index c237838af68..529a5c30171 100644
--- a/gradle/validation/spotless.gradle
+++ b/gradle/validation/spotless.gradle
@@ -95,7 +95,7 @@ configure(project(":solr").subprojects) { prj ->
// Emit a custom message about how to fix formatting errors.
tasks.matching { task -> task.name == "spotlessJavaCheck" }.configureEach {
- runToFixMessage.set("\nIMPORTANT: run the top-level './gradlew tidy' to
format code automatically (see help/formatting.txt for more info).")
+ runToFixMessage.set("\nIMPORTANT: run the top-level './gradlew tidy' to
format code automatically (see help/gradle-help/formatting.txt for more info).")
}
// Add an alias to 'spotlessApply' simply called 'tidy' and wire up
diff --git a/solr/docker/build.gradle b/solr/docker/build.gradle
index 34a51603bc9..0efa18dc309 100644
--- a/solr/docker/build.gradle
+++ b/solr/docker/build.gradle
@@ -415,7 +415,7 @@ task createDockerfileOfficial {
if (''.equals(releaseGpgFingerprint)) {
gradle.taskGraph.whenReady { graph ->
if ( graph.hasTask(tasks.createDockerfileOfficialFull) ||
graph.hasTask(tasks.createDockerfileOfficialSlim) ) {
- throw new GradleException("No GPG keyName found, please see
help/publishing.txt (GPG key is neccessary to create Dockerfile.official)")
+ throw new GradleException("No GPG keyName found, please see
dev-docs/gradle-help/publishing.txt (GPG key is neccessary to create
Dockerfile.official)")
}
}
}
