From 433e5536362738967b5a594b672524bea3bbe86b Mon Sep 17 00:00:00 2001 From: Scott Stults Date: Fri, 8 Nov 2024 17:38:24 -0500 Subject: [PATCH] Fix some docs that were still referring to ES and old documentation website (#66) --- CONTRIBUTING.md | 43 ++++++++++++++----------------------------- README.md | 4 ++-- 2 files changed, 16 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 206be2aa..56951ff7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,7 +41,7 @@ You can clean your project files (such as switching a branch), with ### Juggling Multiple Java Versions -Elastic is pretty religious about upgrading Java versions. This means if a month ago, you developed the plugin with Java 10, you might need Java 12 for the latest. You might just want to keep multiple JDK versions on your laptop, and be able to switch between them, by setting `JAVA_HOME` accordingly: +OpenSearch is pretty religious about upgrading Java versions. This means if a month ago, you developed the plugin with Java 10, you might need Java 12 for the latest. You might just want to keep multiple JDK versions on your laptop, and be able to switch between them, by setting `JAVA_HOME` accordingly: ``` export JAVA11_HOME=/Library/Java/JavaVirtualMachines/jdk-11.0.1.jdk/Contents/Home/ @@ -63,26 +63,26 @@ You can use a tool called [direnv](https://github.com/direnv/direnv) to change y We of course welcome all kinds of pull requests, bug fixes, enhancements, etc. Please simply create your own fork of the repo, and send us a PR for our review. Run the full build process (`./gradlew clean check`) and confirm all tests & integration tests pass. -Be patient, as maintainers have day jobs, and the plugin is relatively stable at this point. Which means we get around to it within a week or so. If you haven't heard from us after a week, please don't be afraid to bump, or bother us on [search relevance slack](http://o19s.com/slack). +Be patient, as maintainers have day jobs, and the plugin is relatively stable at this point. Which means we get around to it within a week or so. If you haven't heard from us after a week, please don't be afraid to bump, or bother us on [search relevance slack](http://opensourceconnections.com/slack). ## OpenSearch Version-Specific Branches OpenSearch insists that any plugin is built against the full major.minor.patch version of the plugin. So if you have a plugin for 6.6.1 and you run 6.6.2 in production, you won't be able to install it. -As a practice, we maintain a branch per OpenSearch version, prefixed by ES. Such as `es_6_6`. We will publish any updated builds for the OpenSearch 6.6 version out of this branch (almost always just minor version updates). Sometimes we've been thoughtful about every minor version of 6.6, sometimes not. +As a practice, we maintain a branch per OpenSearch version, prefixed by OS. Such as `os_6_6`. We will publish any updated builds for the OpenSearch 6.6 version out of this branch (almost always just minor version updates). Sometimes we've been thoughtful about every minor version of 6.6, sometimes not. -### Upgrading to latest OpenSearch major/minor version (ie `es_6_7`) +### Upgrading to latest OpenSearch major/minor version (ie `os_6_7`) -Upgrading to the latest ES version is a great way to help us out, and get your feet wet. The first step is to open `gradle.properties`, and change the ES/Lucene version numbers in the dependencies to the version you wish to upgrade to. We recommend trying to build, (it'll likely fail) making a branch name with the es version number (ie `es_6_7`), and then sending us a "Work in Progress" PR to master. This will let us rally around the (sometimes annoyingly painful) upgrade as a team. +Upgrading to the latest OS version is a great way to help us out, and get your feet wet. The first step is to open `gradle.properties`, and change the OS/Lucene version numbers in the dependencies to the version you wish to upgrade to. We recommend trying to build, (it'll likely fail) making a branch name with the os version number (ie `os_6_7`), and then sending us a "Work in Progress" PR to master. This will let us rally around the (sometimes annoyingly painful) upgrade as a team. #### Gradlew Wrapper and Java Upgrade -The first thing you'll want to do when upgrading OpenSearch LTR is upgrading your Java version. We recommend getting the latest OpenJDK from [jdk.java.net](http://jdk.java.net). Ensure your JAVA_HOME is pointed at where you unzip the JDK contents. See "Juggling Multiple Java Versions" above. Be sure to update the travis.yml to this JDK version. +The first thing you'll want to do when upgrading OpenSearch LTR is upgrading your Java version. We recommend getting the latest OpenJDK from [jdk.java.net](http://jdk.java.net). Ensure your JAVA_HOME is pointed at where you unzip the JDK contents. See "Juggling Multiple Java Versions" above. -The gradlew / gradlew.bat also usually need to be ugpraded to latest. You'll get an error when you run `./gradlew clean check` telling you what gradle to upgrade to. Unfortunately there's a catch 22: you can't run the gradle upgrade task precisely because of the gradle error that Elastic's build system outputs. So here's what I do +The gradlew / gradlew.bat also usually need to be ugpraded to latest. You'll get an error when you run `./gradlew clean check` telling you what gradle to upgrade to. Unfortunately there's a catch 22: you can't run the gradle upgrade task precisely because of the gradle error that OpenSearch's build system outputs. So here's what I do ``` -mv build.gradle /tmp/ # Get the Elastic LTR gradle file out of the way, dont worry, you can use git to get it back! +mv build.gradle /tmp/ # Get the OpenSearch LTR gradle file out of the way, dont worry, you can use git to get it back! ./gradlew stop # Stop any existing gradle daemons ./gradlew wrapper --gradle-version 6.4 #Upgrade (here to 6.4) git checkout build.gradle # Restore build.gradle @@ -91,15 +91,15 @@ git checkout build.gradle # Restore build.gradle #### OpenSearch Code Spelunking! -A lot of the upgrade will involve understanding how OpenSearch's code has changed (such as from `6.6` to `6.7`) that impacts our code base. For example, our code may inherit from some OpenSearch base class that's changed/been refactored between versions. You'll spend a lot of your time in the [OpenSearch repo](http://github.com/elastic/opensearch), going to the file (like a base class) that changed, finding the commit that caused the change, and then seeing how other, similar parts of the Elastic code base (like other plugins), responded to the change. Then we attempt to make that change to the relevant pieces of our code. +A lot of the upgrade will involve understanding how OpenSearch's code has changed (such as from `6.6` to `6.7`) that impacts our code base. For example, our code may inherit from some OpenSearch base class that's changed/been refactored between versions. You'll spend a lot of your time in the [OpenSearch repo](https://github.com/opensearch-project/OpenSearch), going to the file (like a base class) that changed, finding the commit that caused the change, and then seeing how other, similar parts of the OpenSearch code base (like other plugins), responded to the change. Then we attempt to make that change to the relevant pieces of our code. -## Backporting Bug Fixes / Features to Older Elastic Plugin Versions +## Backporting Bug Fixes / Features to Older Plugin Versions -The general rule is master tracks to the last ES version upgrade we did. And master also has the latest & greatest ES plugin features/bug fixes. +The general rule is master tracks to the last OS version upgrade we did. And master also has the latest & greatest OS plugin features/bug fixes. But, you say, you're a happy user of the plugin on version 6.6. That's what's in production, and you aren't exactly going to upgrade to the latest OpenSearch just to get the features / bug fixes added since then for this humble plugin. What should you do? -Should you send in a PR to that ES version? Well from the maintainers point of view, this gets tricky to track. If 6.6 has feature X but 6.7 doesn't, but instead has feature Y, how do we track & understand which ES plugin versions have which features? What 'plugin version' should it be? If you are in a position where you need to backport a lot of features, get comfortable building and deploying the plugin yourself for your own production needs. +Should you send in a PR to that OS version? Well from the maintainers point of view, this gets tricky to track. If 6.6 has feature X but 6.7 doesn't, but instead has feature Y, how do we track & understand which OS plugin versions have which features? What 'plugin version' should it be? If you are in a position where you need to backport a lot of features, get comfortable building and deploying the plugin yourself for your own production needs. We WILL often accept simple bug fixes on a relatively conservative basis ('obviously broken' stuff). @@ -109,26 +109,11 @@ Documentation is the undersung hero of every open source project! People who wri ## Docs development -[Docs](/docs) are built using Sphinx and written in reStructuredText. After [installing sphinx](https://www.sphinx-doc.org/en/master/index.html) (`pip install sphinx`) rebuild the docs with: - -``` -cd docs -make html -``` - -In another tab, you can simply run your favorite HTTP server: - -``` -python -m http.server -``` - -Visit [localhost:8000](http://localhost:8000) and browse to the `_build/html` directory in your browser to view the built docs. - -Docs changes at master will be automatically built and deployed to readthedocs. +[Docs](https://github.com/opensearch-project/documentation-website/tree/main/_search-plugins/ltr) are maintained in a separate project. The [CONTRIBUTING](https://github.com/opensearch-project/documentation-website/blob/main/CONTRIBUTING.md) page has further instructions. ## Docs Content / Editorial Guidelines -Most people come to this plugin, unfamiliar with the basic Learning to Rank workflow. We want this documentation to read as a walkthrough of the Learning to Rank workflow, without getting into the 'advanced' stuff yet. So save the caveats and wherefores to the later section (ie "Advanced Functionality") and keep the 80% 'what you need to know' to the chapters working to tell a story on how to do Learning to Rank. +Most people come to this plugin unfamiliar with the basic Learning to Rank workflow. We want this documentation to read as a walkthrough of the Learning to Rank workflow, without getting into the 'advanced' stuff yet. So save the caveats and wherefores to the later section (ie "Advanced Functionality") and keep the 80% 'what you need to know' to the chapters working to tell a story on how to do Learning to Rank. # Other questions? Get in touch! diff --git a/README.md b/README.md index a7bda6c2..1382ea82 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Important Notice -This is a fork of https://github.com/o19s/elasticsearch-learning-to-rank to work with OpenSearch. It's a rewrite of some parts to be able to work with OpenSearch. Please refer to official documentation of [Elasticsearch Learning to Rank](http://elasticsearch-learning-to-rank.readthedocs.io) for usage. +This is a fork of https://github.com/o19s/elasticsearch-learning-to-rank to work with OpenSearch. It's a rewrite of some parts to be able to work with OpenSearch. Please refer to official documentation of [OpenSearch Learning to Rank](https://opensearch.org/docs/latest/search-plugins/ltr/index/) for usage. The OpenSearch Learning to Rank plugin uses machine learning to improve search relevance ranking. The original Elasticsearch LTR plugin powers search at places like Wikimedia Foundation and Snagajob. @@ -57,7 +57,7 @@ A custom image of [OpenSearch](https://hub.docker.com/r/opensearchproject/opense This image was created for the [Search with Machine Learning](https://corise.com/course/search-with-machine-learning?utm_source=daniel) course and [Search Fundamentals](https://corise.com/course/search-fundamentals?utm_source=daniel) taught by Grant Ingersoll and Daniel Tunkelang. -See the [Elasticsearch Learning to Rank](https://elasticsearch-learning-to-rank.readthedocs.io/en/latest/index.html) documentation for details on how to us. +See the [OpenSearch Learning to Rank](https://opensearch.org/docs/latest/search-plugins/ltr/index/) documentation for details on how to use. ## Building