[DOCS] Clarify upgrades and edit generally #3138
Merged
+30
−27
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
🔍 Preview links for changed docs |
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR updates the Python client documentation to improve clarity, structure, and accuracy. The changes modernize the content with better explanations of compatibility, feature descriptions, and client usage.
- Added navigation metadata and improved page title
- Updated compatibility section with a clearer table and explanations
- Reorganized content flow with better placement of examples and tips
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
marciw
requested review from
a team,
flobernd,
ketkee-aryamane,
picandocodigo and
pquentin
marciw
changed the title
miguelgrinberg
approved these changes
Nov 3, 2025
Contributor
|
@marciw The lint failure is unrelated, I'll fix that separately. |
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
|
The backport to To backport manually, run these commands in your terminal: # Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-9.0 9.0
# Navigate to the new working tree
cd .worktrees/backport-9.0
# Create a new branch
git switch --create backport-3138-to-9.0
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 06f25a0f370c21e511b75e02a87d3e7056e2a00e
# Push it to GitHub
git push --set-upstream origin backport-3138-to-9.0
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-9.0Then, create a pull request where the |
github-actions bot
pushed a commit
that referenced
this pull request
Nov 12, 2025
* Revise upgrade section; do a general edit * fix mis-paste * More edits * Review comments + more cleanup (cherry picked from commit 06f25a0)
github-actions bot
pushed a commit
that referenced
this pull request
Nov 12, 2025
* Revise upgrade section; do a general edit * fix mis-paste * More edits * Review comments + more cleanup (cherry picked from commit 06f25a0)
miguelgrinberg
pushed a commit
that referenced
this pull request
Nov 20, 2025
* Revise upgrade section; do a general edit * fix mis-paste * More edits * Review comments + more cleanup (cherry picked from commit 06f25a0) Co-authored-by: Marci W <[email protected]>
miguelgrinberg
pushed a commit
that referenced
this pull request
Nov 20, 2025
* Revise upgrade section; do a general edit * fix mis-paste * More edits * Review comments + more cleanup (cherry picked from commit 06f25a0) Co-authored-by: Marci W <[email protected]>
pquentin
reviewed
Nov 21, 2025
| As of version 8.0, {{es}} offers a [compatibility mode](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) for smoother upgrades. In compatibility mode, you can upgrade your {{es}} cluster to the next major version while continuing to use your existing client during the transition. | ||
|
|
||
| For example, to upgrade a system that uses {{es}} 8.x you can upgrade the {{es}} server to 9.x first, and the 8.x Python {{es}} client will continue to work (aside from any breaking changes, which should be listed in the server release notes). You can continue using the 8.x client during the server migration, and only upgrade it once the server migration is complete. The process is described in detail in the [REST API compatibility workflow](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/compatibility#_rest_api_compatibility_workflow) section of the {{es}} documentation. | ||
| For example, if you're upgrading {{es}} from 8.x to 9.x, you can continue to use the 8.x Python client during and after the {{es}} server upgrade, with the exception of [breaking changes](../release-notes/breaking-changes.md). |
Member
There was a problem hiding this comment.
This links to the breaking changes for the Python client, which are irrelevant here since the client remains on 8.x. We need to link to the Elasticsearch release notes instead.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
👁️ Preview docs/reference/index.md
Summary of changes
❗ Notes for reviewers
TODO
Clarify "outages" (whether clients need hot-swapping during major upgrades) per Upgrade from 7.17 guide docs-content#3398 (comment)<-- will do this in a follow-up issue; going to merge this in its current state as a "phase 1" edit