Apache
/
lucene
mirror of https://github.com/apache/lucene.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update dev-docs (#919)

This commit is contained in:
Shai Erera 2022-05-23 11:13:07 +03:00 committed by GitHub
parent d17c6056d8
commit 4d02335154
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 31 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
dev-docs/README.adoc
View File

@ -16,6 +16,4 @@
// specific language governing permissions and limitations
// under the License.
This directory includes information for the Lucene project overall.
Also look in `lucene/dev-docs` for Lucene developer information and `solr/dev-docs` for Solr developer information.
This directory includes information for Lucene developers.

30
dev-docs/dev-utilities.adoc
View File

@ -1,30 +0,0 @@
= Developer Utilities
:toc: left
// This is probably going to get split soon, but for the moment, since we only have one dev-docs directory...
== Lucene
TODO: add something here :)
== Solr
=== Cluster on localhost
At times, it is important to do manual testing on a running server, and in many cases it is a good idea to test in a clustered environment to ensure that features play nice both locally and across nodes. To lower the barrier for realistic local testing, there is a script at `solr/cloud-dev/cloud.sh`. Typical usage of the script is:
NOTE: This script only supports POSIX environments. There is no similar .bat script at this time.
1. Copy the script to a location outside the lucene-solr working copy. Trying to use it from within the working copy will leave you fighting version control to avoid checking in files.
2. Edit the script to provide a proper back reference to your working copy for `DEFAULT_VCS_WORKSPACE` (the default is `../code/lucene-solr`)
3. Chmod cloud.sh to make it executable
4. Start a local zookeeper instance. This zookeeper must be running on localhost, but the port can be adjusted with a `-z` option passed to the script.
5. run ./cloud.sh new -r
The command in the final step will:
1. Recompile and package (`-r`) the solr checkout found at `DEFAULT_VCS_WORKSPACE` (but not run the tests).
2. The tarball produced by step 1 is then extracted in a directory that is a peer to cloud.sh and named for the current date (such as `./2021-02-21`).
3. A node at the top level of zookeeper is created and named for the canonical path of this directory to serve as a zkchroot for this deployment.
4. Start solr on ports 8981, 8982, 8983 and 8984 with listening debugger ports on 5001, 5002, 5003, and 5004.
5. Each solr instance will place its data and solr.log in a corresponding directory such as `./2021-02-21/n1`, `./2021-02-21/n2` etc.
The script supports `start`, `stop` and `restart` commands, and a variety of options detailed in the extensive introductory comment in cloud.sh. You should expect that comment to contain the latest information and if it contradicts this document it likely is more correct.

56
dev-docs/working-between-major-versions.adoc
View File

@ -16,48 +16,52 @@
// specific language governing permissions and limitations
// under the License.
Working between multiple major versions of `lucene-solr` is often a necessary part of committing code, due to backports and testing.
For some versions, this is an even bigger issue because `8.x` and `9.x` use different build systems, ant and gradle.
Switching between these branches will result in many files left around that are not tracked by the other branch.
Working between multiple major versions of `lucene` is often a necessary part of committing code, due to backports and
testing. For some versions, this is an even bigger issue because `8.x` and `9.x` use different build systems, ant and
gradle. Switching between these branches will result in many files left around that are not tracked by the other branch.
Even when the build system between branches is the same, major refactoring can produce the same issues.
These orphaned files can impact the use of `precommit`, IntelliJ, and other tools.
== Git Worktree
https://git-scm.com/docs/git-worktree[Git worktree] is a feature of git that allows you to have different directories store separate checkouts of the same repository, at the same time.
The git metadata is shared between the different directories, so any remotes added or local commits made from one worktree are available to all other worktrees as well.
https://git-scm.com/docs/git-worktree[Git worktree] is a feature of git that allows you to have different directories
store separate checkouts of the same repository, at the same time. The git metadata is shared between the different
directories, so any remotes added or local commits made from one worktree are available to all other worktrees as well.
For Lucene-Solr, this allows us to have separate directories (worktrees) that manage the checkouts of `master` and `branch_8x` (or any other major branch).
One can make a commit on `master`, then easily switch directories and cherry-pick the commit onto `branch_8x` without having to worry about gradle or ant files.
This setup also allows the commit to be tested on `master` and `branch_8x` simultaneously.
For Lucene, this allows us to have separate directories (worktrees) that manage the checkouts of `main` and `branch_8x`
(or any other major branch). One can make a commit on `main`, then easily switch directories and cherry-pick the commit
onto `branch_8x` without having to worry about gradle or ant files. This setup also allows the commit to be tested on
`main` and `branch_8x` simultaneously.
=== Setup
Wherever you store your source code, create a root folder for lucene-solr.
Wherever you store your source code, create a root folder for lucene.
```
mkdir lucene-solr
```
[source]
----
mkdir lucene
----
This folder is not a git folder however. Instead, it will hold all of our lucene-solr git checkouts.
This folder is not a git folder. Instead, it will hold all of our lucene git checkouts.
```bash
cd lucene-solr
# Master will be the main lucene-solr checkout, that all worktrees stem from.
git clone git@github.com:apache/lucene-solr.git master
cd master
[source,bash]
----
cd lucene
# main will be the main lucene checkout, that all worktrees stem from.
git clone git@github.com:apache/lucene.git main
cd main
# For each branch that you want a separate directory created for, add a worktree
git worktree add ../8x branch_8x
# If you plan on working on older versions of Solr as well, make worktrees for them too
git worktree add ../7x branch_7x
```
git worktree add ../9x branch_9x
----
=== Using the Worktrees
It's not necessary to create a worktree for every branch you are working on.
Creating repositories for each relevant major version is likely sufficient, because the differences between minor versions is likely not great enough to require a whole new folder.
Therefore most developers will only need 2, master and the lastest major version.
Whenever working on a minor release branch, you can easily use the worktree that corresponds to the same major version.
Creating repositories for each relevant major version is likely sufficient, because the differences between minor
versions is likely not great enough to require a whole new folder.
Therefore, most developers will only need two: main and the latest major version. Whenever working on a minor release
branch, you can easily use the worktree that corresponds to the same major version.
If you are using IntelliJ, you will likely want to load each of the worktrees as a separate project.
That way when you switch between them, IntelliJ will not have to re-build the project fully.
That way when you switch between them, IntelliJ will not have to re-build the project fully.