Skip to content

πŸ™Œ OpenHands: AI-Driven Development

docs(AGENTS.md): add guidance to preserve tool versions when regenerating lockfiles (#13561)

aivong-openhandsa198599d917f
diff --git a/AGENTS.md b/AGENTS.md
index 811f3bdcf0..f352a51a0a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -36,6 +36,42 @@ then re-run the command to ensure it passes. Common issues include:
- Be especially careful with `git reset --hard` after staging files, as it will remove accidentally staged files
- When remote has new changes, use `git fetch upstream && git rebase upstream/<branch>` on the same branch
+## Lockfile Regeneration (Preserve Original Tool Versions)
+
+When regenerating lockfiles (poetry.lock, uv.lock, etc.), you MUST use the same tool version that originally generated the lockfile to avoid unnecessary diff noise. Each lockfile contains a version header indicating which tool version was used.
+
+### Poetry (poetry.lock)
+
+1. Extract the version from the lockfile header:
+ ```bash
+ POETRY_VERSION=$(grep -m1 "^# This file is automatically @generated by Poetry" poetry.lock | sed 's/.*Poetry \([0-9.]*\).*/\1/')
+ ```
+2. If a version is found, install that specific version:
+ ```bash
+ pipx install poetry==$POETRY_VERSION --force
+ ```
+3. Then regenerate the lockfile:
+ ```bash
+ poetry lock --no-update
+ ```
+
+### uv (uv.lock)
+
+1. Extract the version from the lockfile header:
+ ```bash
+ UV_VERSION=$(grep -m1 "^# This file was autogenerated by uv" uv.lock | sed 's/.*uv version \([0-9.]*\).*/\1/')
+ ```
+2. If a version is found, install that specific version:
+ ```bash
+ pipx install uv==$UV_VERSION --force
+ ```
+3. Then regenerate the lockfile:
+ ```bash
+ uv lock
+ ```
+
+This ensures that lockfile updates only contain actual dependency changes, not tool version migration artifacts.
+
## PR-Specific Artifacts (`.pr/` directory)
When working on a PR that requires design documents, scripts meant for development-only, or other temporary artifacts that should NOT be merged to main, store them in a `.pr/` directory at the repository root.