This is an automated email from the ASF dual-hosted git repository.
epugh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/solr.git
The following commit(s) were added to refs/heads/main by this push:
new 53f2f45b3ee Migrate gradle help files into a subdir of dev-docs for
findability (#3685)
53f2f45b3ee is described below
commit 53f2f45b3ee7791c53ed06ecd3c048272d7ab40d
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/dependency-upgrades.adoc | 8 ++++----
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 +-
18 files changed, 44 insertions(+), 20 deletions(-)
diff --git a/dev-docs/dependency-upgrades.adoc
b/dev-docs/dependency-upgrades.adoc
index 6db8075de89..12a13ff0232 100644
--- a/dev-docs/dependency-upgrades.adoc
+++ b/dev-docs/dependency-upgrades.adoc
@@ -22,7 +22,7 @@ Keeping them up-to-date is crucial for a number of reasons:
* minimizing the risk of critical CVE vulnerabilities by staying on a recent
and supported version
* avoiding "dependency hell", that can arise from falling too far behind
-Read the
https://github.com/apache/solr/blob/main/help/dependencies.txt[help/dependencies.txt]
file for an in-depth
+Read the
https://github.com/apache/solr/blob/main/dev-docs/gradle-help/dependencies.txt[dev-docs/gradle-help/dependencies.txt]
file for an in-depth
explanation of how dependencies are managed.
== Manual dependency upgrades
@@ -34,11 +34,11 @@ To upgrade a dependency, you need to run through a number
of steps:
where the locked version of other dependencies also changes.
4. Run `./gradlew kotlinUpgradeYarnLock` to update the kotlin-js-store
lockfile used for the new UI.
Most of the cases it will not have any changes.
-5. In case of a conflict, resolve the conflict according to
`help/dependencies.txt`
-6. Update the license and notice files of the changed dependencies. See
`help/dependencies.txt` for details.
+5. In case of a conflict, resolve the conflict according to
`dev-docs/gradle-help/dependencies.txt`
+6. Update the license and notice files of the changed dependencies. See
`dev-docs/gradle-help/dependencies.txt` for details.
7. Run `./gradlew updateLicenses` to re-generate SHA1 checksums of the new jar
files.
8. Once in a while, a new version of a dependency will transitively bring in
brand-new dependencies.
- You'll need to decide whether to keep or exclude them. See
`help/dependencies.txt` for details.
+ You'll need to decide whether to keep or exclude them. See
`dev-docs/gradle-help/dependencies.txt` for details.
=== Constraints and Version Alignment
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 cef7851da0e..23909b42659 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 77e190fc615..cd10ebc8a15 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 a081eb10304..91c3f88deb7 100644
--- a/gradle/validation/spotless.gradle
+++ b/gradle/validation/spotless.gradle
@@ -104,7 +104,7 @@ configure(allprojects) { prj ->
// Emit a custom message about how to fix formatting errors.
tasks.matching { task -> task.name == "spotlessJavaCheck" }.configureEach {
- it.runToFixMessage.set("\nIMPORTANT: run the top-level './gradlew tidy' to
format code automatically (see help/formatting.txt for more info).")
+ it.runToFixMessage.set("\nIMPORTANT: run the top-level './gradlew tidy' to
format code automatically (see dev-docs/gradle-help/formatting.txt for more
info).")
}
// Hook up spotless to tidy and check tasks.
diff --git a/solr/docker/build.gradle b/solr/docker/build.gradle
index bda15db92f1..39bbf58d17f 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)")
}
}
}
