π 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.mdindex 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.