You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@solr.apache.org by GitBox <gi...@apache.org> on 2022/11/13 12:57:59 UTC
[GitHub] [solr] justinrsweeney opened a new pull request, #1177: Adding documentation for how to contribute to Solr
justinrsweeney opened a new pull request, #1177:
URL: https://github.com/apache/solr/pull/1177
https://issues.apache.org/jira/browse/SOLR-16544
# Description
The goal of this PR is to provide improved documentation on how to contribute to Solr.
# Solution
This adds documentation in the dev-docs for the process of forking Solr and providing a PR for changes. Additionally, this includes a new page in the ref docs that will link to those developer docs.
# Tests
N/A
# Checklist
Please review the following and check all that apply:
- [ ] I have reviewed the guidelines for [How to Contribute](https://wiki.apache.org/solr/HowToContribute) and my code conforms to the standards described there to the best of my ability.
- [ ] I have created a Jira issue and added the issue ID to my pull request title.
- [ ] 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)
- [ ] 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](https://github.com/apache/solr/tree/main/solr/solr-ref-guide)
--
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
[GitHub] [solr] epugh commented on pull request #1177: SOLR-16544: Adding documentation for how to contribute to Solr
Posted by GitBox <gi...@apache.org>.
epugh commented on PR #1177:
URL: https://github.com/apache/solr/pull/1177#issuecomment-1343410350
I love what you've done here. So, it feels like you have two potential PR's, one on the contributing to solr and the other on moving various `/help/*.txt` files out into proper `.adoc` formatted docs. Would it make sense to seperate the JVM doc you did into it's own PR, and move all the help docs?
i find those help docs super useful, but I never use the gradle functionatily for them, so I'd rather see them be able to use .adoc power and be in our dev docs folder!
--
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
[GitHub] [solr] justinrsweeney commented on pull request #1177: SOLR-16544: Adding documentation for how to contribute to Solr
Posted by GitBox <gi...@apache.org>.
justinrsweeney commented on PR #1177:
URL: https://github.com/apache/solr/pull/1177#issuecomment-1367451097
> I love what you've done here. So, it feels like you have two potential PR's, one on the contributing to solr and the other on moving various `/help/*.txt` files out into proper `.adoc` formatted docs. Would it make sense to seperate the JVM doc you did into it's own PR, and move all the help docs?
>
> i find those help docs super useful, but I never use the gradle functionatily for them, so I'd rather see them be able to use .adoc power and be in our dev docs folder!
I kept this a bit limited for now to not change all of the `/help/*.txt` docs. At this point I only moved the IDE and JVM ones since those seem the most relevant to getting started with contributing. The others seem to tend towards a bit more advanced use cases that you wouldn't need immediately to get started, although I could see value in moving those at a later point.
--
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
[GitHub] [solr] janhoy commented on pull request #1177: SOLR-16544: Adding documentation for how to contribute to Solr
Posted by GitBox <gi...@apache.org>.
janhoy commented on PR #1177:
URL: https://github.com/apache/solr/pull/1177#issuecomment-1312784982
See my comment in https://issues.apache.org/jira/browse/SOLR-16544
--
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
[GitHub] [solr] epugh commented on pull request #1177: SOLR-16544: Adding documentation for how to contribute to Solr
Posted by GitBox <gi...@apache.org>.
epugh commented on PR #1177:
URL: https://github.com/apache/solr/pull/1177#issuecomment-1366607559
Some great fixes @justinrsweeney here.. Feel free to ping me and @janhoy when you are ready for more review!
--
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
[GitHub] [solr] epugh commented on a diff in pull request #1177: SOLR-16544: Adding documentation for how to contribute to Solr
Posted by GitBox <gi...@apache.org>.
epugh commented on code in PR #1177:
URL: https://github.com/apache/solr/pull/1177#discussion_r1059084425
##########
dev-docs/solr-source-code.adoc:
##########
@@ -0,0 +1,74 @@
+# Working With Solr Source Code
+
+## Building Solr from Source
+
+Download the Java 11 JDK (Java Development Kit) or later. We recommend the OpenJDK
+distribution Eclipse Temurin available from https://adoptium.net/.
+You will need the JDK installed, and the $JAVA_HOME/bin (Windows: %JAVA_HOME%\bin)
+folder included on your command path. To test this, issue a "java -version" command
+from your shell (command prompt) and verify that the Java version is 11 or later. See the xref:jvms.adoc[JVM developer doc] for more information on Gradle and JVMs.
+
+Clone the latest Apache Solr source code directly from the Git repository: <https://solr.apache.org/community.html#version-control>.
+Alternatively, you can download the Apache Solr distribution, from https://solr.apache.org/downloads.html and unzip the distribution to a folder of your choice, e.g. C:\solr or ~/solr.
+
+Solr uses https://gradle.org/[Gradle] as the build
+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 dev` will create a Solr executable suitable for development.
+cd to `./solr/packaging/build/dev` and run the `bin/solr` script
+to start Solr.
+
+NOTE: `gradlew` is the "Gradle Wrapper" and will automatically download and
+start using the correct version of Gradle for Solr.
+
+NOTE: `./gradlew help` will print a list of high-level tasks. There are also a
+number of plain-text files in <source folder root>/help.
+
+The first time you run Gradle, it will create a file "gradle.properties" that
+contains machine-specific settings. Normally you can use this file as-is, but it
+can be modified if necessary.
+
+Note as well that the gradle build does not create or copy binaries throughout the
+source repository so you need to switch to the packaging output folder `./solr/packaging/build`;
+the rest of the instructions below remain identical. The packaging directory
+is rewritten on each build.
+
+If you want to build the documentation, type `./gradlew -p solr documentation`.
+
+`./gradlew check` will assemble Solr and run all validation tasks unit tests.
+
+To build the final Solr artifacts run `./gradlew assemble`.
+
+Lastly, there is developer oriented documentation in `./dev-docs/README.adoc` that
+you may find useful in working with Solr.
+
+## Running Solr in Docker
Review Comment:
awesome, looks great...
--
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
[GitHub] [solr] janhoy commented on a diff in pull request #1177: SOLR-16544: Adding documentation for how to contribute to Solr
Posted by GitBox <gi...@apache.org>.
janhoy commented on code in PR #1177:
URL: https://github.com/apache/solr/pull/1177#discussion_r1044441376
##########
CONTRIBUTING.md:
##########
@@ -0,0 +1,34 @@
+# Contribute To Solr
+
+Thank you for your interest in contributing to the Apache Solr project. Solr continues to improve via the many contributions of developers around the world and new contributions are welcomed and encouraged.
+
+Your suggestions, comments and comments on Doris can be made directly through the [Apache Solr JIRA](https://issues.apache.org/jira/projects/SOLR/issues).
Review Comment:
```suggestion
Your suggestions and comments can be made directly through the [Apache Solr JIRA](https://issues.apache.org/jira/projects/SOLR/issues).
```
##########
CONTRIBUTING.md:
##########
@@ -0,0 +1,34 @@
+# Contribute To Solr
+
+Thank you for your interest in contributing to the Apache Solr project. Solr continues to improve via the many contributions of developers around the world and new contributions are welcomed and encouraged.
+
+Your suggestions, comments and comments on Doris can be made directly through the [Apache Solr JIRA](https://issues.apache.org/jira/projects/SOLR/issues).
+
+There are many ways to participate in and contribute to Solr, such as: code implementation, test implementation, documentation improvements.
+
+If you have any questions along the way, you can reach out to the community using the resources provided [here](https://solr.apache.org/community.html#mailing-lists-chat).
+
+## How To Contribute
+
+Information on how to contribute can be found [here](https://github.com/apache/solr/blob/main/dev-docs/how-to-contribute.adoc).
Review Comment:
Instead of 'here' links, try to spell it out. Also, can the adoc link be relative and still work on github.com?
```suggestion
Information on how to contribute can be found in [dev-docs/how-to-contribute.adoc](https://github.com/apache/solr/blob/main/dev-docs/how-to-contribute.adoc).
```
##########
CONTRIBUTING.md:
##########
@@ -0,0 +1,34 @@
+# Contribute To Solr
+
+Thank you for your interest in contributing to the Apache Solr project. Solr continues to improve via the many contributions of developers around the world and new contributions are welcomed and encouraged.
+
+Your suggestions, comments and comments on Doris can be made directly through the [Apache Solr JIRA](https://issues.apache.org/jira/projects/SOLR/issues).
+
+There are many ways to participate in and contribute to Solr, such as: code implementation, test implementation, documentation improvements.
+
+If you have any questions along the way, you can reach out to the community using the resources provided [here](https://solr.apache.org/community.html#mailing-lists-chat).
+
+## How To Contribute
+
+Information on how to contribute can be found [here](https://github.com/apache/solr/blob/main/dev-docs/how-to-contribute.adoc).
+
+## Contributing Documentation
+
+One very helpful area for contribution to Solr is via documentation improvements and additions to help make Solr easier to use for others. You can read more about how to modify and update Solr documentation [here](https://github.com/apache/solr/blob/main/solr/solr-ref-guide/README.adoc).
Review Comment:
```suggestion
One very helpful area for contribution to Solr is via documentation improvements and additions to help make Solr easier to use for others. You can read more about how to modify and update Solr documentation in the [Solr Reference Guide README](https://github.com/apache/solr/blob/main/solr/solr-ref-guide/README.adoc).
```
##########
CONTRIBUTING.md:
##########
@@ -0,0 +1,34 @@
+# Contribute To Solr
+
+Thank you for your interest in contributing to the Apache Solr project. Solr continues to improve via the many contributions of developers around the world and new contributions are welcomed and encouraged.
+
+Your suggestions, comments and comments on Doris can be made directly through the [Apache Solr JIRA](https://issues.apache.org/jira/projects/SOLR/issues).
+
+There are many ways to participate in and contribute to Solr, such as: code implementation, test implementation, documentation improvements.
+
+If you have any questions along the way, you can reach out to the community using the resources provided [here](https://solr.apache.org/community.html#mailing-lists-chat).
+
+## How To Contribute
+
+Information on how to contribute can be found [here](https://github.com/apache/solr/blob/main/dev-docs/how-to-contribute.adoc).
+
+## Contributing Documentation
+
+One very helpful area for contribution to Solr is via documentation improvements and additions to help make Solr easier to use for others. You can read more about how to modify and update Solr documentation [here](https://github.com/apache/solr/blob/main/solr/solr-ref-guide/README.adoc).
+
Review Comment:
Add also links to dev-docs and `solr-site` repo README to let people know they can contribute to that part of the docs as well.
##########
dev-docs/how-to-contribute.adoc:
##########
@@ -0,0 +1,23 @@
+# How To Contribute
+
+The Apache Solr Github Repository is located here: https://github.com/apache/solr. Typically all contributions to Solr are developed on a fork of the Solr repository, then opened as PRs against the `main` branch in the solr repository. These PRs are then linked to an open JIRA issue and members of the community will review, comment, approve, and commit changes.
+
+Please keep in mind that the Solr is community driven with many members taking their own personal time to help respond to issue and review PRs. Be open to feedback and discussions and maintain a respectful approach.
Review Comment:
```suggestion
Please keep in mind that the project is community driven, with many members taking their own personal time to help respond to issue and review PRs. Be open to feedback and discussions and maintain a respectful approach. Read our https://solr.apache.org/community.html#code-of-conduct[code of conduct] for more.
```
##########
CONTRIBUTING.md:
##########
@@ -0,0 +1,34 @@
+# Contribute To Solr
+
+Thank you for your interest in contributing to the Apache Solr project. Solr continues to improve via the many contributions of developers around the world and new contributions are welcomed and encouraged.
+
+Your suggestions, comments and comments on Doris can be made directly through the [Apache Solr JIRA](https://issues.apache.org/jira/projects/SOLR/issues).
+
+There are many ways to participate in and contribute to Solr, such as: code implementation, test implementation, documentation improvements.
+
+If you have any questions along the way, you can reach out to the community using the resources provided [here](https://solr.apache.org/community.html#mailing-lists-chat).
+
+## How To Contribute
+
+Information on how to contribute can be found [here](https://github.com/apache/solr/blob/main/dev-docs/how-to-contribute.adoc).
+
+## Contributing Documentation
+
+One very helpful area for contribution to Solr is via documentation improvements and additions to help make Solr easier to use for others. You can read more about how to modify and update Solr documentation [here](https://github.com/apache/solr/blob/main/solr/solr-ref-guide/README.adoc).
+
+## Working With Solr Source Code
+
+Information on how to work with Solr source code and the build system can be found [here](https://github.com/apache/solr/blob/main/dev-docs/solr-source-code.adoc).
+
+## IDE Support
+
+Information on IDE support can be found [here](https://github.com/apache/solr/blob/main/dev-docs/IDEs.adoc).
Review Comment:
Same comment about 'here' applies
##########
CONTRIBUTING.md:
##########
@@ -0,0 +1,34 @@
+# Contribute To Solr
+
+Thank you for your interest in contributing to the Apache Solr project. Solr continues to improve via the many contributions of developers around the world and new contributions are welcomed and encouraged.
+
+Your suggestions, comments and comments on Doris can be made directly through the [Apache Solr JIRA](https://issues.apache.org/jira/projects/SOLR/issues).
+
+There are many ways to participate in and contribute to Solr, such as: code implementation, test implementation, documentation improvements.
+
+If you have any questions along the way, you can reach out to the community using the resources provided [here](https://solr.apache.org/community.html#mailing-lists-chat).
+
+## How To Contribute
+
+Information on how to contribute can be found [here](https://github.com/apache/solr/blob/main/dev-docs/how-to-contribute.adoc).
+
+## Contributing Documentation
+
+One very helpful area for contribution to Solr is via documentation improvements and additions to help make Solr easier to use for others. You can read more about how to modify and update Solr documentation [here](https://github.com/apache/solr/blob/main/solr/solr-ref-guide/README.adoc).
+
+## Working With Solr Source Code
+
+Information on how to work with Solr source code and the build system can be found [here](https://github.com/apache/solr/blob/main/dev-docs/solr-source-code.adoc).
Review Comment:
```suggestion
Information on how to work with Solr source code and the build system can be found in the [developer documentation](https://github.com/apache/solr/blob/main/dev-docs/solr-source-code.adoc).
```
##########
CONTRIBUTING.md:
##########
@@ -0,0 +1,34 @@
+# Contribute To Solr
+
+Thank you for your interest in contributing to the Apache Solr project. Solr continues to improve via the many contributions of developers around the world and new contributions are welcomed and encouraged.
+
+Your suggestions, comments and comments on Doris can be made directly through the [Apache Solr JIRA](https://issues.apache.org/jira/projects/SOLR/issues).
+
+There are many ways to participate in and contribute to Solr, such as: code implementation, test implementation, documentation improvements.
+
+If you have any questions along the way, you can reach out to the community using the resources provided [here](https://solr.apache.org/community.html#mailing-lists-chat).
+
+## How To Contribute
+
+Information on how to contribute can be found [here](https://github.com/apache/solr/blob/main/dev-docs/how-to-contribute.adoc).
+
+## Contributing Documentation
+
+One very helpful area for contribution to Solr is via documentation improvements and additions to help make Solr easier to use for others. You can read more about how to modify and update Solr documentation [here](https://github.com/apache/solr/blob/main/solr/solr-ref-guide/README.adoc).
+
+## Working With Solr Source Code
+
+Information on how to work with Solr source code and the build system can be found [here](https://github.com/apache/solr/blob/main/dev-docs/solr-source-code.adoc).
+
+## IDE Support
+
+Information on IDE support can be found [here](https://github.com/apache/solr/blob/main/dev-docs/IDEs.adoc).
+
+## JVM Support
+
+Information on JVMs can be found [here](https://github.com/apache/solr/blob/main/dev-docs/jvms.adoc).
+
+## FAQs
+
+Review FAQs [here](https://github.com/apache/solr/blob/main/dev-docs/FAQ.adoc)
Review Comment:
Same comment about 'here' applies.
BTW: Is this FAQ really up to date? If not, better not link to it?
##########
dev-docs/how-to-contribute.adoc:
##########
@@ -0,0 +1,23 @@
+# How To Contribute
+
+The Apache Solr Github Repository is located here: https://github.com/apache/solr. Typically all contributions to Solr are developed on a fork of the Solr repository, then opened as PRs against the `main` branch in the solr repository. These PRs are then linked to an open JIRA issue and members of the community will review, comment, approve, and commit changes.
+
+Please keep in mind that the Solr is community driven with many members taking their own personal time to help respond to issue and review PRs. Be open to feedback and discussions and maintain a respectful approach.
+
+## Setup for Contributing
+In order to get setup you will need a fork of the Apache Solr repository and an account in the ASF Jira (usable for all Apache projects).
+
+1. Create a fork of the https://github.com/apache/solr[Solr repository] into your own personal account or a your corporate organization account using the Github instructions provided here: https://docs.github.com/en/get-started/quickstart/fork-a-repo.
+2. Create an account in the ASF Jira: https://issues.apache.org/jira/login.jsp which you will use to create new issues.
+
+## Making a New Contribution
+In order to make a new contribution to Solr you will use the fork you have created above.
+
+1. Create a new Jira issue in the Solr project: https://issues.apache.org/jira/projects/SOLR/issues
+2. Create a new branch in your Solr fork to provide a PR for your contribution on the newly created issue. Make any necessary changes for the given bug/feature in that branch. You can use additional information in these dev-docs to build and test your code as well as ensure it passes code quality checks.
+3. Once you are satisfied with your changes, open a PR of your branch against the `main` branch of the apache/solr repository. When you open a PR on your fork, this should be the default option.
+* The title of your PR should include the Solr Jira issue that you opened, i.e. `SOLR-12345: New feature`.
+* The PR description will automatically populate with a pre-set template that you will need to fill out.
+* The PR will run a gradle pre-commit task that will do some basic checks of your changes. This is run as a Github Action and the results can be viewed from your PR.
+* If you properly named your PR you will see it automatically linked to your Jira issue when you view the issue.
+4. At this point, you will need a Solr committer to review your change and help to get it merged upstream. You can use the https://solr.apache.org/community.html[Solr Developers Mailing List] to get attention to your issue.
Review Comment:
Should we mention PR draft state? It can be useful if you know there is more work to do...
##########
dev-docs/how-to-contribute.adoc:
##########
@@ -0,0 +1,23 @@
+# How To Contribute
+
+The Apache Solr Github Repository is located here: https://github.com/apache/solr. Typically all contributions to Solr are developed on a fork of the Solr repository, then opened as PRs against the `main` branch in the solr repository. These PRs are then linked to an open JIRA issue and members of the community will review, comment, approve, and commit changes.
+
+Please keep in mind that the Solr is community driven with many members taking their own personal time to help respond to issue and review PRs. Be open to feedback and discussions and maintain a respectful approach.
+
+## Setup for Contributing
+In order to get setup you will need a fork of the Apache Solr repository and an account in the ASF Jira (usable for all Apache projects).
+
+1. Create a fork of the https://github.com/apache/solr[Solr repository] into your own personal account or a your corporate organization account using the Github instructions provided here: https://docs.github.com/en/get-started/quickstart/fork-a-repo.
+2. Create an account in the ASF Jira: https://issues.apache.org/jira/login.jsp which you will use to create new issues.
Review Comment:
Currently users have to request an account through the mailing lists...
##########
CONTRIBUTING.md:
##########
@@ -0,0 +1,34 @@
+# Contribute To Solr
+
+Thank you for your interest in contributing to the Apache Solr project. Solr continues to improve via the many contributions of developers around the world and new contributions are welcomed and encouraged.
+
+Your suggestions, comments and comments on Doris can be made directly through the [Apache Solr JIRA](https://issues.apache.org/jira/projects/SOLR/issues).
+
+There are many ways to participate in and contribute to Solr, such as: code implementation, test implementation, documentation improvements.
+
+If you have any questions along the way, you can reach out to the community using the resources provided [here](https://solr.apache.org/community.html#mailing-lists-chat).
+
+## How To Contribute
+
+Information on how to contribute can be found [here](https://github.com/apache/solr/blob/main/dev-docs/how-to-contribute.adoc).
+
+## Contributing Documentation
+
+One very helpful area for contribution to Solr is via documentation improvements and additions to help make Solr easier to use for others. You can read more about how to modify and update Solr documentation [here](https://github.com/apache/solr/blob/main/solr/solr-ref-guide/README.adoc).
+
+## Working With Solr Source Code
+
+Information on how to work with Solr source code and the build system can be found [here](https://github.com/apache/solr/blob/main/dev-docs/solr-source-code.adoc).
+
+## IDE Support
+
+Information on IDE support can be found [here](https://github.com/apache/solr/blob/main/dev-docs/IDEs.adoc).
+
+## JVM Support
+
+Information on JVMs can be found [here](https://github.com/apache/solr/blob/main/dev-docs/jvms.adoc).
Review Comment:
Same comment about 'here' applies
##########
dev-docs/solr-source-code.adoc:
##########
@@ -0,0 +1,76 @@
+# Working With Solr Source Code
+
+## Building Solr from Source
+
+Download the Java 11 JDK (Java Development Kit) or later. We recommend the OpenJDK
+distribution Eclipse Temurin available from https://adoptium.net/.
+You will need the JDK installed, and the $JAVA_HOME/bin (Windows: %JAVA_HOME%\bin)
+folder included on your command path. To test this, issue a "java -version" command
+from your shell (command prompt) and verify that the Java version is 11 or later. See https://github.com/apache/solr/blob/main/dev-docs/jvms.adoc[here] for more information on Gradle and JVMs.
+
+Download the Apache Solr distribution, from https://solr.apache.org/downloads.html.
+Unzip the distribution to a folder of your choice, e.g. C:\solr or ~/solr
+Alternately, you can obtain a copy of the latest Apache Solr source code
Review Comment:
Should not git be the first option we mention, and "Alternatively you can download the source..."?
##########
dev-docs/how-to-contribute.adoc:
##########
@@ -0,0 +1,23 @@
+# How To Contribute
+
+The Apache Solr Github Repository is located here: https://github.com/apache/solr. Typically all contributions to Solr are developed on a fork of the Solr repository, then opened as PRs against the `main` branch in the solr repository. These PRs are then linked to an open JIRA issue and members of the community will review, comment, approve, and commit changes.
+
+Please keep in mind that the Solr is community driven with many members taking their own personal time to help respond to issue and review PRs. Be open to feedback and discussions and maintain a respectful approach.
+
+## Setup for Contributing
+In order to get setup you will need a fork of the Apache Solr repository and an account in the ASF Jira (usable for all Apache projects).
+
+1. Create a fork of the https://github.com/apache/solr[Solr repository] into your own personal account or a your corporate organization account using the Github instructions provided here: https://docs.github.com/en/get-started/quickstart/fork-a-repo.
+2. Create an account in the ASF Jira: https://issues.apache.org/jira/login.jsp which you will use to create new issues.
+
+## Making a New Contribution
+In order to make a new contribution to Solr you will use the fork you have created above.
+
+1. Create a new Jira issue in the Solr project: https://issues.apache.org/jira/projects/SOLR/issues
+2. Create a new branch in your Solr fork to provide a PR for your contribution on the newly created issue. Make any necessary changes for the given bug/feature in that branch. You can use additional information in these dev-docs to build and test your code as well as ensure it passes code quality checks.
+3. Once you are satisfied with your changes, open a PR of your branch against the `main` branch of the apache/solr repository. When you open a PR on your fork, this should be the default option.
Review Comment:
Before opening a PR it is useful to run `tidy` and `check -x test` for a shorter feedback loop. Sometimes `updateLicenses` is also needed, so the easiest is to fold all three into one:
```suggestion
3. Once you are satisfied with your changes, get your branch ready for a PR by running `./gradlew tidy updateLicenses check -x test`. This will format your source code, update licenses of any dependency version changes and run all pre-commit tests. Commit the changes.
4. Open a PR of your branch against the `main` branch of the apache/solr repository. When you open a PR on your fork, this should be the default option.
```
--
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
[GitHub] [solr] janhoy commented on pull request #1177: SOLR-16544: Adding documentation for how to contribute to Solr
Posted by GitBox <gi...@apache.org>.
janhoy commented on PR #1177:
URL: https://github.com/apache/solr/pull/1177#issuecomment-1381916581
@justinrsweeney Since this is a substantial contribution, feel free (if you like) to add a line to CHANGES.txt under "Other" header in 9.2 section, adding your own name in parenthesis for more visible credit than just the git commit. After that, Eric or I can merge it.
--
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
[GitHub] [solr] janhoy merged pull request #1177: SOLR-16544: Adding documentation for how to contribute to Solr
Posted by GitBox <gi...@apache.org>.
janhoy merged PR #1177:
URL: https://github.com/apache/solr/pull/1177
--
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
[GitHub] [solr] justinrsweeney commented on pull request #1177: SOLR-16544: Adding documentation for how to contribute to Solr
Posted by GitBox <gi...@apache.org>.
justinrsweeney commented on PR #1177:
URL: https://github.com/apache/solr/pull/1177#issuecomment-1367451644
@epugh @janhoy Thank you for the initial feedback, I think this is at a point now for further review when you have some time!
--
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
[GitHub] [solr] justinrsweeney commented on pull request #1177: SOLR-16544: Adding documentation for how to contribute to Solr
Posted by GitBox <gi...@apache.org>.
justinrsweeney commented on PR #1177:
URL: https://github.com/apache/solr/pull/1177#issuecomment-1384415908
Done, thanks for the review and feedback 😄
--
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
[GitHub] [solr] epugh commented on a diff in pull request #1177: SOLR-16544: Adding documentation for how to contribute to Solr
Posted by GitBox <gi...@apache.org>.
epugh commented on code in PR #1177:
URL: https://github.com/apache/solr/pull/1177#discussion_r1059066649
##########
dev-docs/solr-source-code.adoc:
##########
@@ -0,0 +1,74 @@
+# Working With Solr Source Code
+
+## Building Solr from Source
+
+Download the Java 11 JDK (Java Development Kit) or later. We recommend the OpenJDK
+distribution Eclipse Temurin available from https://adoptium.net/.
+You will need the JDK installed, and the $JAVA_HOME/bin (Windows: %JAVA_HOME%\bin)
+folder included on your command path. To test this, issue a "java -version" command
+from your shell (command prompt) and verify that the Java version is 11 or later. See the xref:jvms.adoc[JVM developer doc] for more information on Gradle and JVMs.
+
+Clone the latest Apache Solr source code directly from the Git repository: <https://solr.apache.org/community.html#version-control>.
+Alternatively, you can download the Apache Solr distribution, from https://solr.apache.org/downloads.html and unzip the distribution to a folder of your choice, e.g. C:\solr or ~/solr.
+
+Solr uses https://gradle.org/[Gradle] as the build
+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 dev` will create a Solr executable suitable for development.
+cd to `./solr/packaging/build/dev` and run the `bin/solr` script
+to start Solr.
+
+NOTE: `gradlew` is the "Gradle Wrapper" and will automatically download and
+start using the correct version of Gradle for Solr.
+
+NOTE: `./gradlew help` will print a list of high-level tasks. There are also a
+number of plain-text files in <source folder root>/help.
+
+The first time you run Gradle, it will create a file "gradle.properties" that
+contains machine-specific settings. Normally you can use this file as-is, but it
+can be modified if necessary.
+
+Note as well that the gradle build does not create or copy binaries throughout the
+source repository so you need to switch to the packaging output folder `./solr/packaging/build`;
+the rest of the instructions below remain identical. The packaging directory
+is rewritten on each build.
+
+If you want to build the documentation, type `./gradlew -p solr documentation`.
+
+`./gradlew check` will assemble Solr and run all validation tasks unit tests.
+
+To build the final Solr artifacts run `./gradlew assemble`.
+
+Lastly, there is developer oriented documentation in `./dev-docs/README.adoc` that
+you may find useful in working with Solr.
+
+## Running Solr in Docker
Review Comment:
It feels to me a bit odd taht solr in Docker is in this file. I suspect that we would have enough developer docs related to Docker and solr to justify it's own page??? For example, i recently saw someone wondering how to connect intellij to solr insdie of a docker image ;-)
--
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
[GitHub] [solr] justinrsweeney commented on a diff in pull request #1177: SOLR-16544: Adding documentation for how to contribute to Solr
Posted by GitBox <gi...@apache.org>.
justinrsweeney commented on code in PR #1177:
URL: https://github.com/apache/solr/pull/1177#discussion_r1059084031
##########
dev-docs/solr-source-code.adoc:
##########
@@ -0,0 +1,74 @@
+# Working With Solr Source Code
+
+## Building Solr from Source
+
+Download the Java 11 JDK (Java Development Kit) or later. We recommend the OpenJDK
+distribution Eclipse Temurin available from https://adoptium.net/.
+You will need the JDK installed, and the $JAVA_HOME/bin (Windows: %JAVA_HOME%\bin)
+folder included on your command path. To test this, issue a "java -version" command
+from your shell (command prompt) and verify that the Java version is 11 or later. See the xref:jvms.adoc[JVM developer doc] for more information on Gradle and JVMs.
+
+Clone the latest Apache Solr source code directly from the Git repository: <https://solr.apache.org/community.html#version-control>.
+Alternatively, you can download the Apache Solr distribution, from https://solr.apache.org/downloads.html and unzip the distribution to a folder of your choice, e.g. C:\solr or ~/solr.
+
+Solr uses https://gradle.org/[Gradle] as the build
+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 dev` will create a Solr executable suitable for development.
+cd to `./solr/packaging/build/dev` and run the `bin/solr` script
+to start Solr.
+
+NOTE: `gradlew` is the "Gradle Wrapper" and will automatically download and
+start using the correct version of Gradle for Solr.
+
+NOTE: `./gradlew help` will print a list of high-level tasks. There are also a
+number of plain-text files in <source folder root>/help.
+
+The first time you run Gradle, it will create a file "gradle.properties" that
+contains machine-specific settings. Normally you can use this file as-is, but it
+can be modified if necessary.
+
+Note as well that the gradle build does not create or copy binaries throughout the
+source repository so you need to switch to the packaging output folder `./solr/packaging/build`;
+the rest of the instructions below remain identical. The packaging directory
+is rewritten on each build.
+
+If you want to build the documentation, type `./gradlew -p solr documentation`.
+
+`./gradlew check` will assemble Solr and run all validation tasks unit tests.
+
+To build the final Solr artifacts run `./gradlew assemble`.
+
+Lastly, there is developer oriented documentation in `./dev-docs/README.adoc` that
+you may find useful in working with Solr.
+
+## Running Solr in Docker
Review Comment:
Agreed, there is also a bunch of Docker information in the Solr Ref Guide, so I just split that out into its own dev doc and added a link out to the Ref Guide. Can provide a place to continue to add Docker specific development info.
--
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