You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@solr.apache.org by David Smiley <ds...@apache.org> on 2026/07/04 23:05:48 UTC
Proposal: drop docs/ folder from Solr binary distribution
I'd like to propose removing the docs/ folder from the Solr binary
distribution and folding its useful content into README.txt instead.
Background: docs/ in the binary distro comes from solr/documentation in
the source repo, and its content is published online for each release
already -- e.g. https://solr.apache.org/docs/10_0_0/ for 10.0.0.
Looking at what's actually in the folder today (10.0.0):
docs/index.html -- a single HTML page whose only content is
two links: one to the online docs, one
to docs/changes/Changes.html
docs/solr.svg -- logo used by index.html
docs/changes/Changes.html -- an HTML-rendered changelog
docs/changes/*.css -- stylesheets for the above
None of this is actually documentation -- it's a redirect page plus a
second, redundant copy of the changelog. We already ship CHANGELOG.md at
the top level of the distro, so docs/changes/ is pure duplication in a
different format. And README.txt already has a line pointing at
docs/index.html for "the online version of the Javadoc API documentation
and Tutorial" -- we can just replace that with the direct link and cut
out the middleman page entirely.
Proposal:
- Stop bundling docs/ in the binary distribution.
- Add the online docs link (and the per-release changes link, if
desired) directly into README.txt's existing "Files included in an
Apache Solr binary distribution" section.
This shrinks the distro slightly and removes a folder whose entire
purpose is now better served by a couple of README lines.
You can see the current contents for yourself by downloading the 10.0.0
slim distro and looking at docs/:
https://www.apache.org/dyn/closer.lua/solr/solr/10.0.0/solr-10.0.0-slim.tgz
Thoughts?
Somewhat out of scope, but IMO the solr/documentation folder feels weird in
name/scope/purpose. Maybe renaming to site-docs to better reflect that the
destination/delivery is a website. I'm not sure if incorporating it into
the solr-site repo makes sense.
~ David Smiley
Apache Lucene/Solr Search Developer
http://www.linkedin.com/in/davidwsmiley
Re: Proposal: drop docs/ folder from Solr binary distribution
Posted by David Smiley <ds...@apache.org>.
The "optics" of the proposal look misleading on the surface -- no longer
shipping documentation? The reality is that we *aleady* stopped doing so
since like Solr 9. The change proposal here, as implemented in the PR,
removes only redundant info from what's already present in the release.
FWIW I concur with our *past* decision to stop shipping documentation in
the release. Houston pushed for that; got it done. Perhaps a case could
be made to include more content in our full release (but not the "slim"
release).
Re: Proposal: drop docs/ folder from Solr binary distribution
Posted by Mike Drob <md...@mdrob.com>.
I'll provide some historical context - I believe the distribution ships
with the docs for the benefit of air-gapped deployments and SREs so that
they would know exactly which version of the documentation applies to the
bundle they are using. I don't know if these assumptions still hold as much
relevance, but please think of the operators before making this change.
Mike
On Wed, Jul 15, 2026 at 6:09 PM David Smiley <ds...@apache.org> wrote:
> https://github.com/apache/solr/pull/4641
>
> This allows "./gradlew dev" (and assemble for that matter) to no longer
> depend on documentation, which I found means I could start Solr from a
> clean slate significantly faster. "./gradlew runDev".
>
> I also disable a couple modules BTW: disableJsClient=true
> disableUiModule=true And consequently no "node" usage :-) Good riddance.
>
> On Wed, Jul 15, 2026 at 8:17 AM Jason Gerlowski <ge...@gmail.com>
> wrote:
>
> > +1 to your plan David - seems like a nice simplification.
> >
> > On Tue, Jul 7, 2026 at 11:27 AM Eric Pugh
> > <ep...@opensourceconnections.com> wrote:
> > >
> > > I agree that if we have README that ships, that is the place for the
> > pointer. And the changelog probably doesn’t need to ship either if we
> > have a pointer in the README to the URL?
> > https://solr.apache.org/docs/10_0_0/changes/Changes.html ?
> > >
> > >
> > > I do like keeping our ref guide docs combined with Solr…. A strength
> > is that because we this “monorepo” like setup, that code changes and Ref
> > Guide changes stay together.
> > >
> > > Arguably, we should move things like documentation up to the root of
> the
> > project.. ./solr/blah is often just an artifact of the time when Lucene
> > and Solr shared a single repo.
> > >
> > > Eric
> > >
> > >
> > > > On Jul 4, 2026, at 7:05 PM, David Smiley <ds...@apache.org> wrote:
> > > >
> > > > I'd like to propose removing the docs/ folder from the Solr binary
> > > > distribution and folding its useful content into README.txt instead.
> > > >
> > > > Background: docs/ in the binary distro comes from solr/documentation
> in
> > > > the source repo, and its content is published online for each release
> > > > already -- e.g. https://solr.apache.org/docs/10_0_0/ <
> > https://solr.apache.org/docs/10_0_0> for 10.0.0.
> > > >
> > > > Looking at what's actually in the folder today (10.0.0):
> > > >
> > > > docs/index.html -- a single HTML page whose only content is
> > > > two links: one to the online docs, one
> > > > to docs/changes/Changes.html
> > > > docs/solr.svg -- logo used by index.html
> > > > docs/changes/Changes.html -- an HTML-rendered changelog
> > > > docs/changes/*.css -- stylesheets for the above
> > > >
> > > > None of this is actually documentation -- it's a redirect page plus a
> > > > second, redundant copy of the changelog. We already ship CHANGELOG.md
> > at
> > > > the top level of the distro, so docs/changes/ is pure duplication in
> a
> > > > different format. And README.txt already has a line pointing at
> > > > docs/index.html for "the online version of the Javadoc API
> > documentation
> > > > and Tutorial" -- we can just replace that with the direct link and
> cut
> > > > out the middleman page entirely.
> > > >
> > > > Proposal:
> > > > - Stop bundling docs/ in the binary distribution.
> > > > - Add the online docs link (and the per-release changes link, if
> > > > desired) directly into README.txt's existing "Files included in an
> > > > Apache Solr binary distribution" section.
> > > >
> > > > This shrinks the distro slightly and removes a folder whose entire
> > > > purpose is now better served by a couple of README lines.
> > > >
> > > > You can see the current contents for yourself by downloading the
> 10.0.0
> > > > slim distro and looking at docs/:
> > > >
> >
> https://www.apache.org/dyn/closer.lua/solr/solr/10.0.0/solr-10.0.0-slim.tgz
> > <
> >
> https://www.apache.org/dyn/closer.lua/solr/solr/10.0.0/solr-10.0.0-slim.tgz
> > >
> > > >
> > > > Thoughts?
> > > >
> > > > Somewhat out of scope, but IMO the solr/documentation folder feels
> > weird in
> > > > name/scope/purpose. Maybe renaming to site-docs to better reflect
> that
> > the
> > > > destination/delivery is a website. I'm not sure if incorporating it
> > into
> > > > the solr-site repo makes sense.
> > > >
> > > > ~ David Smiley
> > > > Apache Lucene/Solr Search Developer
> > > > http://www.linkedin.com/in/davidwsmiley <
> > http://www.linkedin.com/in/davidwsmiley>
> > >
> > > Disclaimer
> > >
> > > The information contained in this communication from the sender is
> > confidential. It is intended solely for use by the recipient and others
> > authorized to receive it. If you are not the recipient, you are hereby
> > notified that any disclosure, copying, distribution or taking action in
> > relation of the contents of this information is strictly prohibited and
> may
> > be unlawful.
> > >
> > > This email has been scanned for viruses and malware, and may have been
> > automatically archived by Mimecast, a leader in email security and cyber
> > resilience. Mimecast integrates email defenses with brand protection,
> > security awareness training, web security, compliance and other essential
> > capabilities. Mimecast helps protect large and small organizations from
> > malicious activity, human error and technology failure; and to lead the
> > movement toward building a more resilient world. To find out more, visit
> > our website.
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> > For additional commands, e-mail: dev-help@solr.apache.org
> >
> >
>
Re: Proposal: drop docs/ folder from Solr binary distribution
Posted by David Smiley <ds...@apache.org>.
https://github.com/apache/solr/pull/4641
This allows "./gradlew dev" (and assemble for that matter) to no longer
depend on documentation, which I found means I could start Solr from a
clean slate significantly faster. "./gradlew runDev".
I also disable a couple modules BTW: disableJsClient=true
disableUiModule=true And consequently no "node" usage :-) Good riddance.
On Wed, Jul 15, 2026 at 8:17 AM Jason Gerlowski <ge...@gmail.com>
wrote:
> +1 to your plan David - seems like a nice simplification.
>
> On Tue, Jul 7, 2026 at 11:27 AM Eric Pugh
> <ep...@opensourceconnections.com> wrote:
> >
> > I agree that if we have README that ships, that is the place for the
> pointer. And the changelog probably doesn’t need to ship either if we
> have a pointer in the README to the URL?
> https://solr.apache.org/docs/10_0_0/changes/Changes.html ?
> >
> >
> > I do like keeping our ref guide docs combined with Solr…. A strength
> is that because we this “monorepo” like setup, that code changes and Ref
> Guide changes stay together.
> >
> > Arguably, we should move things like documentation up to the root of the
> project.. ./solr/blah is often just an artifact of the time when Lucene
> and Solr shared a single repo.
> >
> > Eric
> >
> >
> > > On Jul 4, 2026, at 7:05 PM, David Smiley <ds...@apache.org> wrote:
> > >
> > > I'd like to propose removing the docs/ folder from the Solr binary
> > > distribution and folding its useful content into README.txt instead.
> > >
> > > Background: docs/ in the binary distro comes from solr/documentation in
> > > the source repo, and its content is published online for each release
> > > already -- e.g. https://solr.apache.org/docs/10_0_0/ <
> https://solr.apache.org/docs/10_0_0> for 10.0.0.
> > >
> > > Looking at what's actually in the folder today (10.0.0):
> > >
> > > docs/index.html -- a single HTML page whose only content is
> > > two links: one to the online docs, one
> > > to docs/changes/Changes.html
> > > docs/solr.svg -- logo used by index.html
> > > docs/changes/Changes.html -- an HTML-rendered changelog
> > > docs/changes/*.css -- stylesheets for the above
> > >
> > > None of this is actually documentation -- it's a redirect page plus a
> > > second, redundant copy of the changelog. We already ship CHANGELOG.md
> at
> > > the top level of the distro, so docs/changes/ is pure duplication in a
> > > different format. And README.txt already has a line pointing at
> > > docs/index.html for "the online version of the Javadoc API
> documentation
> > > and Tutorial" -- we can just replace that with the direct link and cut
> > > out the middleman page entirely.
> > >
> > > Proposal:
> > > - Stop bundling docs/ in the binary distribution.
> > > - Add the online docs link (and the per-release changes link, if
> > > desired) directly into README.txt's existing "Files included in an
> > > Apache Solr binary distribution" section.
> > >
> > > This shrinks the distro slightly and removes a folder whose entire
> > > purpose is now better served by a couple of README lines.
> > >
> > > You can see the current contents for yourself by downloading the 10.0.0
> > > slim distro and looking at docs/:
> > >
> https://www.apache.org/dyn/closer.lua/solr/solr/10.0.0/solr-10.0.0-slim.tgz
> <
> https://www.apache.org/dyn/closer.lua/solr/solr/10.0.0/solr-10.0.0-slim.tgz
> >
> > >
> > > Thoughts?
> > >
> > > Somewhat out of scope, but IMO the solr/documentation folder feels
> weird in
> > > name/scope/purpose. Maybe renaming to site-docs to better reflect that
> the
> > > destination/delivery is a website. I'm not sure if incorporating it
> into
> > > the solr-site repo makes sense.
> > >
> > > ~ David Smiley
> > > Apache Lucene/Solr Search Developer
> > > http://www.linkedin.com/in/davidwsmiley <
> http://www.linkedin.com/in/davidwsmiley>
> >
> > Disclaimer
> >
> > The information contained in this communication from the sender is
> confidential. It is intended solely for use by the recipient and others
> authorized to receive it. If you are not the recipient, you are hereby
> notified that any disclosure, copying, distribution or taking action in
> relation of the contents of this information is strictly prohibited and may
> be unlawful.
> >
> > This email has been scanned for viruses and malware, and may have been
> automatically archived by Mimecast, a leader in email security and cyber
> resilience. Mimecast integrates email defenses with brand protection,
> security awareness training, web security, compliance and other essential
> capabilities. Mimecast helps protect large and small organizations from
> malicious activity, human error and technology failure; and to lead the
> movement toward building a more resilient world. To find out more, visit
> our website.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
> For additional commands, e-mail: dev-help@solr.apache.org
>
>
Re: Proposal: drop docs/ folder from Solr binary distribution
Posted by Jason Gerlowski <ge...@gmail.com>.
+1 to your plan David - seems like a nice simplification.
On Tue, Jul 7, 2026 at 11:27 AM Eric Pugh
<ep...@opensourceconnections.com> wrote:
>
> I agree that if we have README that ships, that is the place for the pointer. And the changelog probably doesn’t need to ship either if we have a pointer in the README to the URL? https://solr.apache.org/docs/10_0_0/changes/Changes.html ?
>
>
> I do like keeping our ref guide docs combined with Solr…. A strength is that because we this “monorepo” like setup, that code changes and Ref Guide changes stay together.
>
> Arguably, we should move things like documentation up to the root of the project.. ./solr/blah is often just an artifact of the time when Lucene and Solr shared a single repo.
>
> Eric
>
>
> > On Jul 4, 2026, at 7:05 PM, David Smiley <ds...@apache.org> wrote:
> >
> > I'd like to propose removing the docs/ folder from the Solr binary
> > distribution and folding its useful content into README.txt instead.
> >
> > Background: docs/ in the binary distro comes from solr/documentation in
> > the source repo, and its content is published online for each release
> > already -- e.g. https://solr.apache.org/docs/10_0_0/ <https://solr.apache.org/docs/10_0_0> for 10.0.0.
> >
> > Looking at what's actually in the folder today (10.0.0):
> >
> > docs/index.html -- a single HTML page whose only content is
> > two links: one to the online docs, one
> > to docs/changes/Changes.html
> > docs/solr.svg -- logo used by index.html
> > docs/changes/Changes.html -- an HTML-rendered changelog
> > docs/changes/*.css -- stylesheets for the above
> >
> > None of this is actually documentation -- it's a redirect page plus a
> > second, redundant copy of the changelog. We already ship CHANGELOG.md at
> > the top level of the distro, so docs/changes/ is pure duplication in a
> > different format. And README.txt already has a line pointing at
> > docs/index.html for "the online version of the Javadoc API documentation
> > and Tutorial" -- we can just replace that with the direct link and cut
> > out the middleman page entirely.
> >
> > Proposal:
> > - Stop bundling docs/ in the binary distribution.
> > - Add the online docs link (and the per-release changes link, if
> > desired) directly into README.txt's existing "Files included in an
> > Apache Solr binary distribution" section.
> >
> > This shrinks the distro slightly and removes a folder whose entire
> > purpose is now better served by a couple of README lines.
> >
> > You can see the current contents for yourself by downloading the 10.0.0
> > slim distro and looking at docs/:
> > https://www.apache.org/dyn/closer.lua/solr/solr/10.0.0/solr-10.0.0-slim.tgz <https://www.apache.org/dyn/closer.lua/solr/solr/10.0.0/solr-10.0.0-slim.tgz>
> >
> > Thoughts?
> >
> > Somewhat out of scope, but IMO the solr/documentation folder feels weird in
> > name/scope/purpose. Maybe renaming to site-docs to better reflect that the
> > destination/delivery is a website. I'm not sure if incorporating it into
> > the solr-site repo makes sense.
> >
> > ~ David Smiley
> > Apache Lucene/Solr Search Developer
> > http://www.linkedin.com/in/davidwsmiley <http://www.linkedin.com/in/davidwsmiley>
>
> Disclaimer
>
> The information contained in this communication from the sender is confidential. It is intended solely for use by the recipient and others authorized to receive it. If you are not the recipient, you are hereby notified that any disclosure, copying, distribution or taking action in relation of the contents of this information is strictly prohibited and may be unlawful.
>
> This email has been scanned for viruses and malware, and may have been automatically archived by Mimecast, a leader in email security and cyber resilience. Mimecast integrates email defenses with brand protection, security awareness training, web security, compliance and other essential capabilities. Mimecast helps protect large and small organizations from malicious activity, human error and technology failure; and to lead the movement toward building a more resilient world. To find out more, visit our website.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@solr.apache.org
For additional commands, e-mail: dev-help@solr.apache.org
Re: Proposal: drop docs/ folder from Solr binary distribution
Posted by Eric Pugh <ep...@opensourceconnections.com>.
I agree that if we have README that ships, that is the place for the pointer. And the changelog probably doesn’t need to ship either if we have a pointer in the README to the URL? https://solr.apache.org/docs/10_0_0/changes/Changes.html ?
I do like keeping our ref guide docs combined with Solr…. A strength is that because we this “monorepo” like setup, that code changes and Ref Guide changes stay together.
Arguably, we should move things like documentation up to the root of the project.. ./solr/blah is often just an artifact of the time when Lucene and Solr shared a single repo.
Eric
> On Jul 4, 2026, at 7:05 PM, David Smiley <ds...@apache.org> wrote:
>
> I'd like to propose removing the docs/ folder from the Solr binary
> distribution and folding its useful content into README.txt instead.
>
> Background: docs/ in the binary distro comes from solr/documentation in
> the source repo, and its content is published online for each release
> already -- e.g. https://solr.apache.org/docs/10_0_0/ <https://solr.apache.org/docs/10_0_0> for 10.0.0.
>
> Looking at what's actually in the folder today (10.0.0):
>
> docs/index.html -- a single HTML page whose only content is
> two links: one to the online docs, one
> to docs/changes/Changes.html
> docs/solr.svg -- logo used by index.html
> docs/changes/Changes.html -- an HTML-rendered changelog
> docs/changes/*.css -- stylesheets for the above
>
> None of this is actually documentation -- it's a redirect page plus a
> second, redundant copy of the changelog. We already ship CHANGELOG.md at
> the top level of the distro, so docs/changes/ is pure duplication in a
> different format. And README.txt already has a line pointing at
> docs/index.html for "the online version of the Javadoc API documentation
> and Tutorial" -- we can just replace that with the direct link and cut
> out the middleman page entirely.
>
> Proposal:
> - Stop bundling docs/ in the binary distribution.
> - Add the online docs link (and the per-release changes link, if
> desired) directly into README.txt's existing "Files included in an
> Apache Solr binary distribution" section.
>
> This shrinks the distro slightly and removes a folder whose entire
> purpose is now better served by a couple of README lines.
>
> You can see the current contents for yourself by downloading the 10.0.0
> slim distro and looking at docs/:
> https://www.apache.org/dyn/closer.lua/solr/solr/10.0.0/solr-10.0.0-slim.tgz <https://www.apache.org/dyn/closer.lua/solr/solr/10.0.0/solr-10.0.0-slim.tgz>
>
> Thoughts?
>
> Somewhat out of scope, but IMO the solr/documentation folder feels weird in
> name/scope/purpose. Maybe renaming to site-docs to better reflect that the
> destination/delivery is a website. I'm not sure if incorporating it into
> the solr-site repo makes sense.
>
> ~ David Smiley
> Apache Lucene/Solr Search Developer
> http://www.linkedin.com/in/davidwsmiley <http://www.linkedin.com/in/davidwsmiley>
Disclaimer
The information contained in this communication from the sender is confidential. It is intended solely for use by the recipient and others authorized to receive it. If you are not the recipient, you are hereby notified that any disclosure, copying, distribution or taking action in relation of the contents of this information is strictly prohibited and may be unlawful.
This email has been scanned for viruses and malware, and may have been automatically archived by Mimecast, a leader in email security and cyber resilience. Mimecast integrates email defenses with brand protection, security awareness training, web security, compliance and other essential capabilities. Mimecast helps protect large and small organizations from malicious activity, human error and technology failure; and to lead the movement toward building a more resilient world. To find out more, visit our website.