SOLR-15242: Consolidate README.md with solr/README.md #610

epugh · 2022-02-08T13:43:31Z

https://issues.apache.org/jira/browse/SOLR-15242

Description

Consolidate README.md with solr/README.md

Solution

Trying not to duplicate things, trying to not get in TOO much depth, but give enoguh so that folks who go to github.com/apache/solr have a nice experience!

Tests

Please describe the tests you've developed or run to confirm this patch implements the feature or solves the problem.

Checklist

Please review the following and check all that apply:

[X ] I have reviewed the guidelines for How to Contribute 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 to contribute to my PR branch. (optional but recommended)
[X ] I have developed this patch against the main branch.
I have run ./gradlew check.
I have added tests for my changes.
I have added documentation for the Reference Guide

…acing the existing README.md and solr/README.md

janhoy

Thanks for doing this Eric. Some random comments

janhoy · 2022-02-08T14:28:02Z

README_v2.md

+For documentation on using the official docker builds, please refer to the [DockerHub page](https://hub.docker.com/_/solr).  
+Up to date documentation for running locally built images of this branch can be found in the [local reference guide](solr/solr-ref-guide/src/running-solr-in-docker.adoc).
+
+There is also a gradle task for building custom Solr images from your local checkout.


Perhaps add a link to dev-docs/docker.adoc - eeh, no, wait that does not exist, I meant help/docker.txt -- eh, sorry, wrong again, it should be solr/docker/gradle-help.txt (why on earth do we have dev-docs spread out this much?) so we don't need to say so much about building Docker locally in the main README.

Hmm, looking a few lines down, I now see that ./gradlew helpDocker actually points to that txt file, but that is not consistent either, would expect all help files to exist in help/.. Well, well.

I'm going to take this as "it's okay" for now then on this comment? Quite agree on your frustration!

Sorry for that placement, there was discussion at the time, but it is long forgotten. I'd be happy to move it to wherever it will make the most sense 🙂

README_v2.md

janhoy · 2022-02-08T14:34:10Z

README_v2.md

+system.  Navigate to the root of your source tree folder and issue the `./gradlew tasks`
+command to see the available options for building, testing, and packaging Solr.
+
+`./gradlew assemble` will create a Solr executable.


Perhaps highlight the ./gradlew dev task instead, as it it creates a build on a stable path and is made for quick developer cycles. Then we won't need to change the README for every release either, replacing the solr-9.0.0-SNAPSHOT string :)

Good suggestion. I added a mention of assemble later on.

janhoy · 2022-02-08T14:38:51Z

README_v2.md

+you may find useful in working with Solr.
+
+
+### Gradle build and IDE support


General about building from source and gradle - perhaps we should make some really good and thorough guides about that topic in dev-docs, and just have a few really basic examples here in the main readme, like ./gradlew dev and cd solr/packaging/dev/ && bin/solr -e techproducts...

But i see that the main focus here is merging the two READMEs, so feel free to postpone dev-docs work to later.

I agree with the sentiment! We should rationalize more the dev-docs and the stuff in ref guide related to development. Or just put dev-docs etc in Ref Guide!

That can be done in followup issues. I think we plan for a separate dev-guide, and not mash everything into ref-guide.

janhoy · 2022-02-08T14:40:11Z

README_v2.md

+
+## Contributing
+
+Please review the [Contributing to Solr Guide](https://cwiki.apache.org/confluence/display/solr/HowToContribute)


Later, the result of https://issues.apache.org/jira/browse/SOLR-15682 will be linked here...

README_v2.md

Co-authored-by: Jan Høydahl <[email protected]>

epugh · 2022-02-10T20:34:19Z

Just added some getting started based on what @chatman did in apache/lucene-solr#2594, thoughts @janhoy ???

gerlowskija

The README looks great, thanks for taking this on Eric.

I have a few questions conceptually about what should be in a top-level README. Most projects I looked up (Kube, Elasticsearch, Opensearch, ZooKeeper, Vespa) have READMEs that are focused pretty tightly on "meta" information: what the project is, contribution, licensing. In these examples, more concrete information (tutorials, docker setup, and detailed startup or development instructions) are covered by sometimes a short blurb and a link out to some other location.

I like that setup personally: it avoids duplication in things like tutorials, and (IMO) runs less risk of overwhelming new users with a wall of text and unfamiliar concepts right out of the gate.

But assuming we're consciously choosing this more inclusive approach, I think this PR is a great stab at it. The prose is clear and the tutorial is helpful

gerlowskija · 2022-07-11T11:46:23Z

README_v2.md

+# Welcome to the Apache Solr project!
+-----------------------------------
+
+Solr is the popular, blazing fast open source enterprise search platform


blazing fast open source enterprise search platform

[0] It feels weird to single out enterprise search here as being our main (only?) use case. We're also an ecommerce search engine, and an analytics engine, etc.

(I understand this language is probably carried over from one of the existing READMEs, and used in many places...no need to fix it here necessarily if you're not interested.)

I completely agree with you @gerlowskija on this... It IS front and center on the website at https://solr.apache.org/ ;-(. Worth a seperate ticket?

Solr is the popular, blazing fast open source search platform for your enterprise, ecommerce, and analytics needs

???

Agreed, we should fix it everywhere. I changed the Official docker image description to remove it. But we should standardize around a common language, and set that everywhere.

@HoustonPutman you want to open a ticket? If you get the consensus, I'd volunteer to do the updates ;-)

https://issues.apache.org/jira/browse/SOLR-16295

We can brainstorm there

gerlowskija · 2022-07-11T12:40:41Z

README_v2.md

+visit the [Solr Reference Guide](https://solr.apache.org/guide/).
+
+## Getting Started
+FIXME maybe put the tutorial that Noble or Ishan wrote???   Then at the end put the examples?


[Q] Alternatively - do we really want a full blown tutorial in our README? At best, it duplicates documentation we have elsewhere. At worst it makes it harder to find the information the reader actually came for.

I agree that we shouldn't have a full-blown tutorial here. We should have links to our actual tutorials, and enhance them if need be.

If we do keep a tutorial here, let's put other stuff before it, like the docker and kubernetes sections. These are smaller and are really just advertising other documentation/sites that people should be checking out.

gerlowskija · 2022-07-11T12:41:36Z

README_v2.md

+
+```
+curl --request POST \
+--url http://localhost:8983/api/collections \


[+1] Thanks for the effort to use the v2 APIs!

[-0] If we are trying to fixup the v2 APIs before marketing them, lets unfortunately continue to use the v1 APIs until they are ready.

(If we plan on keeping the tutorial section)

If we are trying to fixup the v2 APIs

I guess that makes sense, unfortunately. I'd love to get these APIs mostly locked in as soon as we can though, so that we can start pushing them. On that note: anyone reading this should go review the proposed changes to the v2 API here 😛

gerlowskija · 2022-07-11T12:48:27Z

README_v2.md

+
+## Export control
+
+This distribution includes cryptographic software.  The country in


[Q] Is there a legal requirement to have this here, or is it here for practical purposes?

(i.e. This mostly looks like legal boilerplate to me, but I'm not an expert so maybe there's actual nuggets in here useful to sysadmin/security folks?)

Assuming this is here for legal reasons: looking at other projects (e.g. Elasticsearch, Vespa, Zookeeper) who use cryptography similar to Solr, none of them mention export controls in their top level repositories. Maybe we're the rare case of a project actually doing what's legally required, but I suspect we actually don't need this here.

(Also, ./gradlew dependencies makes me think we no longer pull in bouncycastle from TIKA as this suggests.)

epugh · 2022-07-14T16:22:10Z

Hey all.... I am getting the feeling that README_V2 is trying to do too many things. Is it hear to extoll the virtues of Solr? Be your onboarding tutorial? Provide all the depth of the main solr.apache.org site?

I'm going to craft a README_V3 to compare with README_V2 that is narrower in focus and follows more in the vein of other projects with more links.

epugh · 2022-07-14T16:40:54Z

So... check out README_V3.md, which I just put "chapter headings" and some comments....

epugh · 2022-07-14T18:07:19Z

Okay, I think I am liking V3 a lot more over V2... Thoughts? Should I move the tutorial into the ref guide? I like how it uses the new apis and is super compact.... "Index and Query in Five Minutes with Solr"

HoustonPutman · 2022-07-14T20:40:14Z

I like the new v3 implementation a lot!

We do need to keep a separate Readme for the binary distribution, but we can keep that in solr/packaging. That should at least include the parts of the old solr/README.md that mentioned the folder layout, and probably the export control section.

Also maybe the v3 readme should have a section that explains each super (or sub /solr/...) directory in the repository. But maybe that fits better in dev-docs, with a link from the README.

epugh · 2022-07-15T14:30:57Z

@HoustonPutman I'll take it that I'm on the right track.... I'll try and add a solr/packaging/README.md the way you suggested.

I do think trying to explain the code etc is better int he dev docs, and not have the README do too much.

Also, I tried to make it easier to call out resources for new dev's to join. I keep meeting folks who contribute patches and yet ARE NOT on the dev mailing list, or the slack channel for development work...

HoustonPutman

I think this is good to go @epugh !

Consolidate the ./README.md and ./solr/README.md into a new top level README.md optimized for Github. The /solr/README.adoc is now to help a developer understand what the subdirectories are all about. Introduced a new README.txt in the ./solr/packaging directory to ship with the distributions. Co-authored-by: [email protected] <> Co-authored-by: Jan Høydahl <[email protected]> Co-authored-by: Houston Putman <[email protected]>

[email protected] added 2 commits February 8, 2022 14:27

strawperson version of potential new README.md at the top level, repl…

da173d3

…acing the existing README.md and solr/README.md

we appear to still be on freenode, not librera

9cf87bd

epugh marked this pull request as draft February 8, 2022 13:43

epugh requested a review from janhoy February 8, 2022 13:43

janhoy reviewed Feb 8, 2022

View reviewed changes

[email protected] and others added 6 commits February 10, 2022 19:34

we have moved to libera.chat

b67ad39

Update README_v2.md

2a2a32a

Co-authored-by: Jan Høydahl <[email protected]>

updated to latest openjdk

0911f87

use consistent descriptions for examples across README and help output

dfa3089

remove fixme

bd29528

experimenting with adding more detailed docs

6877151

epugh added 2 commits July 9, 2022 20:01

Merge branch 'main' into SOLR-15242

e7b5af3

respond to comments

8426d43

epugh requested review from janhoy and madrob July 10, 2022 00:10

epugh marked this pull request as ready for review July 10, 2022 00:10

tabs to spaces

cf224ad

gerlowskija reviewed Jul 11, 2022

View reviewed changes

skelaton

cf6e6e8

epugh added 4 commits July 14, 2022 13:13

bring in some links

3024f20

a take of moving content to the dev-docs

160b000

finish firt draft content

b43af2e

darn you markdown formatting

f299706

epugh added 3 commits July 14, 2022 16:01

port light weight tutorial into ref guide

5825539

link in tutorial

36e2fdc

better header

28bdc78

better titlte

a31f301

epugh and others added 13 commits July 19, 2022 12:54

README set up for inclusion in our distributions

f9d6535

typo

950b5a3

finalizing the top level readme

657c5c2

Revamp!

7bc921f

finalized our top level README

27d85c4

Provide developer information on sub directories.

a465efe

comments are hard

4c35ef4

Update README.adoc

e90cec1

Update README.adoc

e79a432

fixing links

67c3f0a

Fix links

ee66008

Package new solr binary readme

7c93dae

Merge branch 'main' into SOLR-15242

c0120a2

HoustonPutman approved these changes Jul 19, 2022

View reviewed changes

epugh merged commit a34f9c9 into apache:main Jul 20, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

SOLR-15242: Consolidate README.md with solr/README.md #610

SOLR-15242: Consolidate README.md with solr/README.md #610

epugh commented Feb 8, 2022

janhoy left a comment

janhoy Feb 8, 2022

epugh Feb 10, 2022

HoustonPutman Jul 11, 2022

janhoy Feb 8, 2022

epugh Jul 10, 2022

janhoy Feb 8, 2022

epugh Feb 10, 2022

janhoy Feb 10, 2022

janhoy Feb 8, 2022

epugh commented Feb 10, 2022

gerlowskija left a comment •

edited

Loading

gerlowskija Jul 11, 2022

epugh Jul 11, 2022

HoustonPutman Jul 11, 2022

epugh Jul 14, 2022

HoustonPutman Jul 14, 2022

gerlowskija Jul 11, 2022

HoustonPutman Jul 11, 2022

gerlowskija Jul 11, 2022

HoustonPutman Jul 11, 2022

gerlowskija Jul 14, 2022

gerlowskija Jul 11, 2022

epugh commented Jul 14, 2022

epugh commented Jul 14, 2022

epugh commented Jul 14, 2022

HoustonPutman commented Jul 14, 2022

epugh commented Jul 15, 2022

HoustonPutman left a comment

		you may find useful in working with Solr.


		### Gradle build and IDE support


		## Contributing

		Please review the [Contributing to Solr Guide](https://cwiki.apache.org/confluence/display/solr/HowToContribute)


		## Export control

		This distribution includes cryptographic software. The country in

SOLR-15242: Consolidate README.md with solr/README.md #610

SOLR-15242: Consolidate README.md with solr/README.md #610

Conversation

epugh commented Feb 8, 2022

Description

Solution

Tests

Checklist

janhoy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

epugh commented Feb 10, 2022

gerlowskija left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

epugh commented Jul 14, 2022

epugh commented Jul 14, 2022

epugh commented Jul 14, 2022

HoustonPutman commented Jul 14, 2022

epugh commented Jul 15, 2022

HoustonPutman left a comment

Choose a reason for hiding this comment

gerlowskija left a comment •

edited

Loading