From 712b8c7350b170e137560d7bd444f11aacc0fca9 Mon Sep 17 00:00:00 2001
From: aaronabbott <aaronabbott@google.com>
Date: Fri, 7 Aug 2026 21:00:19 +0000
Subject: [PATCH] docs: add skill for merging and reformatting PRs after Ruff
 120 update

---
 .agents/skills/merge-ruff-120/SKILL.md | 76 ++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 .agents/skills/merge-ruff-120/SKILL.md

diff --git a/.agents/skills/merge-ruff-120/SKILL.md b/.agents/skills/merge-ruff-120/SKILL.md
new file mode 100644
index 0000000000..07b3d3a282
--- /dev/null
+++ b/.agents/skills/merge-ruff-120/SKILL.md
@@ -0,0 +1,76 @@
+---
+name: merge-ruff-120
+description: "Reformat code on a feature branch and merge main cleanly after the Ruff line-length increase from 79 to 120 (merged August 7, 2026, commit 0110bb1d273dbe848312d429326b844da9e86d93, PR #5514). Relevant for branches created before August 2026."
+---
+
+# Merging main and Reformatting Code (Ruff 120 Line Length)
+
+## Overview
+
+In PR #5514 (merged on August 7, 2026, commit `0110bb1d273dbe848312d429326b844da9e86d93`), OpenTelemetry Python updated its Ruff configuration in `pyproject.toml` to increase `line-length` from 79 to 120 characters and reformatted the entire codebase.
+
+Feature branches created prior to August 7, 2026 (before this commit) will encounter extensive merge conflicts if merged directly. This skill instructs an agent on how to detect this situation and perform a clean multi-step merge without formatting conflict markers.
+
+## Detection: When to Use This Skill
+
+An agent can test whether a branch needs this reformatting workflow:
+
+```bash
+# Returns non-zero (exit code 1) if the branch was created BEFORE the Ruff 120 change (August 7, 2026):
+git merge-base --is-ancestor 0110bb1d273dbe848312d429326b844da9e86d93 HEAD
+```
+
+If the commit is **not** an ancestor of `HEAD`, follow the workflow below.
+
+---
+
+## Workflow
+
+Follow these steps on the contributor's feature branch:
+
+### Step 1: Ensure workspace is clean & sync dependencies
+
+```bash
+uv sync --frozen --all-packages
+git fetch origin main
+```
+
+### Step 2: Merge the commit before the line-length change
+
+Merge all changes up to the commit immediately *before* the Ruff 120 reformat:
+
+```bash
+git merge 0110bb1d273dbe848312d429326b844da9e86d93^
+```
+
+Because both sides are still 79-column code, there are zero formatting conflicts. Resolve any real semantic conflicts if present, then commit the merge.
+
+### Step 3: Merge the reformatting commit with `-X ours --no-commit`
+
+Merge the reformat commit, automatically choosing the branch's code on any formatting conflicts and pausing before creating the merge commit:
+
+```bash
+git merge -X ours --no-commit 0110bb1d273dbe848312d429326b844da9e86d93
+```
+
+### Step 4: Format and lint the branch to 120 columns
+
+Ensure `pyproject.toml` has `line-length = 120` and run Ruff directly to format and lint the code:
+
+```bash
+sed -i 's/line-length = 79/line-length = 120/' pyproject.toml
+uv run ruff format
+uv run ruff check --fix
+```
+
+### Step 5: Finalize the merge commit
+
+```bash
+git commit -am "chore: merge Ruff 120 reformat and format branch"
+```
+
+### Step 6: Catch up with latest `main`
+
+```bash
+git merge origin/main
+```