You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@solr.apache.org by "serhiy-bzhezytskyy (via GitHub)" <gi...@apache.org> on 2026/10/02 15:36:31 UTC
[PR] SOLR-18495: Use {name} placeholders for names in Ref Guide URLs [solr]
serhiy-bzhezytskyy opened a new pull request, #5005:
URL: https://github.com/apache/solr/pull/5005
https://issues.apache.org/jira/browse/SOLR-18495
# Description
Names inside URLs and paths in the Ref Guide were written as `_core_name_`, `<collection>`, `collection_name`, `YOUR_COLLECTION` or a literal like `my_collection`, so nothing in the URL said it was meant to be replaced.
# Solution
They are now `{collectionName}`, `{coreName}`, and so on, the same names the V2 API uses for its path parameters, and About This Guide says what the braces mean. Names a page defines itself (`bin/solr create -c mycollection` and the URLs after it) and CLI arguments are unchanged; `implicit-requesthandlers.adoc` follows once #4928 is in.
The braces are escaped (`\{x}`) in prose and tables and plain in `[source]` blocks, where a backslash would be printed. That also fixes `\{string_field}` in the three XML examples of `document-enrichment-with-llms.adoc`.
Written with Claude Code.
# Tests
Full ref-guide build and link check (`:solr:solr-ref-guide:buildLocalAntoraSite` and `checkSiteLinks`) pass, and the built pages show the new names with no stray backslash.
# Checklist
- [x] I have reviewed the guidelines for [How to Contribute](https://github.com/apache/solr/blob/main/CONTRIBUTING.md) and my code conforms to the standards described there to the best of my ability.
- [x] I have created a Jira issue and added the issue ID to my pull request title.
- [x] I have given Solr maintainers [access](https://help.github.com/en/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork) to contribute to my PR branch. (optional but recommended, not available for branches on forks living under an organisation)
- [x] I have developed this patch against the `main` branch.
- [ ] I have run `./gradlew check`.
- [ ] I have added tests for my changes.
- [x] I have added documentation for the [Reference Guide](https://github.com/apache/solr/tree/main/solr/solr-ref-guide)
- [ ] I have added a [changelog entry](https://github.com/apache/solr/blob/main/dev-docs/changelog.adoc) for my change
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
Re: [PR] SOLR-18495: Use {name} placeholders for names in Ref Guide URLs [solr]
Posted by "epugh (via GitHub)" <gi...@apache.org>.
epugh merged PR #5005:
URL: https://github.com/apache/solr/pull/5005
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
Re: [PR] SOLR-18495: Use {name} placeholders for names in Ref Guide URLs [solr]
Posted by "epugh (via GitHub)" <gi...@apache.org>.
epugh commented on PR #5005:
URL: https://github.com/apache/solr/pull/5005#issuecomment-5957090324
Okay, once build finishes I'll merge!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
Re: [PR] SOLR-18495: Use {name} placeholders for names in Ref Guide URLs [solr]
Posted by "serhiy-bzhezytskyy (via GitHub)" <gi...@apache.org>.
serhiy-bzhezytskyy commented on code in PR #5005:
URL: https://github.com/apache/solr/pull/5005#discussion_r4167941964
##########
solr/solr-ref-guide/modules/configuration-guide/pages/coreadmin-api.adoc:
##########
@@ -352,15 +352,15 @@ V1 API::
====
[source,bash]
----
-curl -X GET "http://localhost:8983/solr/admin/cores?action=RENAME&core=currentCoreName&other=newCoreName"
+curl -X GET "http://localhost:8983/solr/admin/cores?action=RENAME&core={currentCoreName}&other=newCoreName"
Review Comment:
The `-X GET` was already on those lines on main, so I took the change back out of this PR; the 48 lines are in their own PR, https://github.com/apache/solr/pull/5007. `-X PUT`, `DELETE` and `POST` stay where they change the request.
##########
solr/solr-ref-guide/modules/configuration-guide/pages/package-manager.adoc:
##########
@@ -140,7 +140,7 @@ If the collection is named `collection1`, the package name is `mypackage`, and t
[source,bash]
----
-curl "http://localhost:8983/api/collections/collection1/config/params" \
+curl "http://localhost:8983/api/collections/{collectionName}/config/params" \
Review Comment:
Right, that one already follows the rule.
##########
solr/solr-ref-guide/modules/getting-started/pages/about-this-guide.adoc:
##########
@@ -73,6 +73,9 @@ As of the 7.2 version of this Guide, these examples are not yet complete - more
The section xref:configuration-guide:v2-api.adoc[] provides more information about how to work with the new API structure, including how to disable it if you choose to do so.
+In URLs and paths, a name in curly braces, such as `\{collectionName}` or `\{coreName}`, stands for a value you replace with your own.
Review Comment:
`AGENTS.md` has a Documentation section that tells agents to update the reference guide, but nothing there says how to write a page. I'll add a line pointing at `dev-docs/ref-guide/asciidoc-syntax.adoc` and this page, as a separate PR.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
Re: [PR] SOLR-18495: Use {name} placeholders for names in Ref Guide URLs [solr]
Posted by "serhiy-bzhezytskyy (via GitHub)" <gi...@apache.org>.
serhiy-bzhezytskyy commented on code in PR #5005:
URL: https://github.com/apache/solr/pull/5005#discussion_r4167962838
##########
solr/solr-ref-guide/modules/getting-started/pages/about-this-guide.adoc:
##########
@@ -73,6 +73,9 @@ As of the 7.2 version of this Guide, these examples are not yet complete - more
The section xref:configuration-guide:v2-api.adoc[] provides more information about how to work with the new API structure, including how to disable it if you choose to do so.
+In URLs and paths, a name in curly braces, such as `\{collectionName}` or `\{coreName}`, stands for a value you replace with your own.
Review Comment:
Opened https://github.com/apache/solr/pull/5008. A correction to what I wrote above: `AGENTS.md` already lists `dev-docs/ref-guide/` in its Developer Docs Index; what it lacked was a pointer from the Documentation bullet, which that PR adds.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
Re: [PR] SOLR-18495: Use {name} placeholders for names in Ref Guide URLs [solr]
Posted by "epugh (via GitHub)" <gi...@apache.org>.
epugh commented on code in PR #5005:
URL: https://github.com/apache/solr/pull/5005#discussion_r4167784139
##########
solr/solr-ref-guide/modules/configuration-guide/pages/coreadmin-api.adoc:
##########
@@ -352,15 +352,15 @@ V1 API::
====
[source,bash]
----
-curl -X GET "http://localhost:8983/solr/admin/cores?action=RENAME&core=currentCoreName&other=newCoreName"
+curl -X GET "http://localhost:8983/solr/admin/cores?action=RENAME&core={currentCoreName}&other=newCoreName"
Review Comment:
Didn't we decide we would NOT have `-X GET` since that's the default in all our curl commands? Can you verify that we didn't do this somehwere else?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
Re: [PR] SOLR-18495: Use {name} placeholders for names in Ref Guide URLs [solr]
Posted by "epugh (via GitHub)" <gi...@apache.org>.
epugh commented on code in PR #5005:
URL: https://github.com/apache/solr/pull/5005#discussion_r4167796346
##########
solr/solr-ref-guide/modules/getting-started/pages/about-this-guide.adoc:
##########
@@ -73,6 +73,9 @@ As of the 7.2 version of this Guide, these examples are not yet complete - more
The section xref:configuration-guide:v2-api.adoc[] provides more information about how to work with the new API structure, including how to disable it if you choose to do so.
+In URLs and paths, a name in curly braces, such as `\{collectionName}` or `\{coreName}`, stands for a value you replace with your own.
Review Comment:
Oh NICE!!!! In fact, I wonder if we need to clue our LLM's better into the existence of this page so we generated better docs?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org
Re: [PR] SOLR-18495: Use {name} placeholders for names in Ref Guide URLs [solr]
Posted by "epugh (via GitHub)" <gi...@apache.org>.
epugh commented on code in PR #5005:
URL: https://github.com/apache/solr/pull/5005#discussion_r4167788831
##########
solr/solr-ref-guide/modules/configuration-guide/pages/package-manager.adoc:
##########
@@ -140,7 +140,7 @@ If the collection is named `collection1`, the package name is `mypackage`, and t
[source,bash]
----
-curl "http://localhost:8983/api/collections/collection1/config/params" \
+curl "http://localhost:8983/api/collections/{collectionName}/config/params" \
Review Comment:
See, here we don't have the `-X GET`... Also, if that is a fix to do in a seperate PR, we can do that.. jsut wanted to make sure we aren't stepping on something..
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org