Skip to content

Commit 28ca0a9

Browse files
LoCoBench Botclaude
LoCoBench Bot
and
claude
committed
feat: US-008 - Create docgen-migration-002: Migration guide from Envoy version upgrade
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 1538b04 commit 28ca0a9

7 files changed

Lines changed: 455 additions & 1 deletion

File tree

‎benchmarks/ccb_docgen/docgen-migration-002/environment/Dockerfile‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
FROM ubuntu:22.04
2+
3+
RUN apt-get update && apt-get install -y \
4+
git \
5+
python3 \
6+
&& rm -rf /var/lib/apt/lists/*
7+
8+
WORKDIR /workspace
9+
10+
# Clone Envoy repo with blob filtering for fast clone
11+
RUN git clone --filter=blob:none --no-checkout https://github.com/envoyproxy/envoy.git envoy-repo
12+
13+
# Create worktrees for v1.30.0 and v1.31.0
14+
WORKDIR /workspace/envoy-repo
15+
RUN git worktree add ../envoy-v1.30 50ea83e602d5da162df89fd5798301e22f5540cf
16+
RUN git worktree add ../envoy-v1.31 7b8baff1758f0a584dcc3cb657b5032000bcb3d7
17+
18+
# Remove the main clone to save space
19+
WORKDIR /workspace
20+
RUN rm -rf envoy-repo
21+
22+
# Verify the versions
23+
RUN cd envoy-v1.30 && git log -1 --oneline
24+
RUN cd envoy-v1.31 && git log -1 --oneline
25+
26+
# Set working directory to workspace root
27+
WORKDIR /workspace

‎benchmarks/ccb_docgen/docgen-migration-002/instruction.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Migration Guide: Envoy External Processing Filter (v1.30 → v1.31)
2+
3+
## Task
4+
5+
Generate a comprehensive migration guide for upgrading the Envoy External Processing (ext_proc) HTTP filter from **version 1.30.0 to version 1.31.0**.
6+
7+
## Context
8+
9+
The workspace contains two versions of the Envoy codebase:
10+
- `/workspace/envoy-v1.30/` - Envoy v1.30.0 (April 2024)
11+
- `/workspace/envoy-v1.31/` - Envoy v1.31.0 (July 2024)
12+
13+
## Scope
14+
15+
Focus specifically on the **External Processing (ext_proc) HTTP filter** configuration and implementation changes. This filter allows external services to process HTTP requests and responses.
16+
17+
Your migration guide should identify and document:
18+
19+
1. **Breaking Changes** - Incompatible configuration or behavioral changes
20+
2. **Deprecated Features** - Fields or modes marked for future removal
21+
3. **New Features** - Added capabilities and configuration options
22+
4. **Configuration Updates** - Required or recommended changes to ext_proc filter configuration
23+
5. **Behavioral Changes** - Modifications to filter behavior or runtime semantics
24+
25+
## Relevant Components
26+
27+
The ext_proc filter is primarily located in:
28+
- Proto definitions: `api/envoy/extensions/filters/http/ext_proc/v3/`
29+
- Implementation: `source/extensions/filters/http/ext_proc/`
30+
- Documentation: `docs/root/configuration/http/http_filters/ext_proc_filter.rst`
31+
32+
## Output Format
33+
34+
Write your migration guide to `/workspace/documentation.md` in Markdown format with the following sections:
35+
36+
1. **Overview** - Summary of the migration and major changes
37+
2. **Breaking Changes** - Critical incompatible changes requiring action
38+
3. **Deprecated Features** - Features marked for deprecation with migration advice
39+
4. **New Features** - New capabilities and how to use them
40+
5. **Migration Steps** - Step-by-step instructions for upgrading configurations
41+
6. **Testing Recommendations** - How to validate the migration
42+
7. **Rollback Guidance** - How to revert if issues occur
43+
44+
## Requirements
45+
46+
- Provide specific proto field names and types
47+
- Include before/after configuration examples for each breaking change
48+
- Explain the motivation or benefit behind major changes
49+
- Cite specific source files where implementations changed
50+
- Recommend best practices for adopting new features
51+
- Identify common migration pitfalls or edge cases
52+
53+
## MCP Advantage
54+
55+
This task benefits from:
56+
- `compare_revisions` to identify changed proto fields and implementation files
57+
- `diff_search` to find all API modifications in the ext_proc filter
58+
- `find_references` to trace configuration usage patterns
59+
- `nls_search` to locate related documentation updates

‎benchmarks/ccb_docgen/docgen-migration-002/task.toml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
[task]
2+
name = "docgen-migration-002"
3+
category = "migration_guide"
4+
language = "cpp"
5+
difficulty = "hard"
6+
time_limit_sec = 1200
7+
8+
[metadata]
9+
description = "Generate migration guide for Envoy External Processing (ext_proc) filter upgrade from v1.30 to v1.31"
10+
tags = ["envoy", "migration", "ext_proc", "filter", "configuration"]

‎benchmarks/ccb_docgen/docgen-migration-002/tests/ground_truth.json‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
{
2+
"scoring_categories": {
3+
"breaking_changes": {
4+
"weight": 0.50,
5+
"items": [
6+
{
7+
"name": "Observability mode deprecates async_mode",
8+
"patterns": [
9+
"async_mode.*deprecat",
10+
"observability.*mode",
11+
"observability_mode"
12+
],
13+
"weight": 0.35
14+
},
15+
{
16+
"name": "HTTP/2 codec change affects ext_proc performance",
17+
"patterns": [
18+
"http2_use_oghttp2",
19+
"HTTP/2.*codec",
20+
"oghttp2.*true"
21+
],
22+
"weight": 0.15
23+
},
24+
{
25+
"name": "Processing mode configuration impacts",
26+
"patterns": [
27+
"ProcessingMode",
28+
"processing_mode.*sent",
29+
"ext_proc service.*response"
30+
],
31+
"weight": 0.20
32+
},
33+
{
34+
"name": "Upstream filter chain support",
35+
"patterns": [
36+
"upstream.*filter",
37+
"ext_proc.*upstream",
38+
"response.*processing"
39+
],
40+
"weight": 0.15
41+
},
42+
{
43+
"name": "New configuration fields required",
44+
"patterns": [
45+
"grpc_initial_metadata",
46+
"metadata_options",
47+
"request_attributes|response_attributes"
48+
],
49+
"weight": 0.15
50+
}
51+
]
52+
},
53+
"migration_steps": {
54+
"weight": 0.30,
55+
"items": [
56+
{
57+
"name": "Replace async_mode with observability_mode",
58+
"patterns": [
59+
"async_mode.*observability_mode",
60+
"migration.*async",
61+
"upgrade.*async_mode"
62+
],
63+
"weight": 0.30
64+
},
65+
{
66+
"name": "Update ProcessingMode configuration",
67+
"patterns": [
68+
"ProcessingMode.*updat",
69+
"configure.*processing.*mode",
70+
"request_header_mode|response_header_mode"
71+
],
72+
"weight": 0.25
73+
},
74+
{
75+
"name": "Test HTTP/2 codec compatibility",
76+
"patterns": [
77+
"test.*http2",
78+
"verify.*oghttp2",
79+
"codec.*compatibility"
80+
],
81+
"weight": 0.15
82+
},
83+
{
84+
"name": "Configure new metadata options",
85+
"patterns": [
86+
"grpc_initial_metadata.*config",
87+
"metadata_options.*set",
88+
"configure.*metadata"
89+
],
90+
"weight": 0.15
91+
},
92+
{
93+
"name": "Validate filter behavior",
94+
"patterns": [
95+
"test.*filter",
96+
"validate.*behavior",
97+
"verify.*processing"
98+
],
99+
"weight": 0.15
100+
}
101+
]
102+
},
103+
"code_examples": {
104+
"weight": 0.15,
105+
"items": [
106+
{
107+
"name": "Before/after async_mode to observability_mode",
108+
"patterns": [
109+
"async_mode.*true",
110+
"observability_mode.*true",
111+
"before.*after"
112+
],
113+
"weight": 0.35
114+
},
115+
{
116+
"name": "New grpc_initial_metadata configuration",
117+
"patterns": [
118+
"grpc_initial_metadata",
119+
"initial.*metadata.*example",
120+
"metadata.*header"
121+
],
122+
"weight": 0.25
123+
},
124+
{
125+
"name": "ProcessingMode configuration example",
126+
"patterns": [
127+
"processing_mode.*\\{",
128+
"request_header_mode.*SEND",
129+
"response_header_mode"
130+
],
131+
"weight": 0.20
132+
},
133+
{
134+
"name": "Upstream filter configuration",
135+
"patterns": [
136+
"upstream.*ext_proc",
137+
"response.*filter.*config",
138+
"apply_without_waiting"
139+
],
140+
"weight": 0.20
141+
}
142+
]
143+
},
144+
"documentation_structure": {
145+
"weight": 0.05,
146+
"items": [
147+
{
148+
"name": "Overview section",
149+
"patterns": [
150+
"##.*[Oo]verview",
151+
"migration.*summary",
152+
"v1\\.30.*v1\\.31"
153+
],
154+
"weight": 0.15
155+
},
156+
{
157+
"name": "Breaking Changes section",
158+
"patterns": [
159+
"##.*[Bb]reaking.*[Cc]hanges",
160+
"incompatible.*changes",
161+
"breaking.*change"
162+
],
163+
"weight": 0.20
164+
},
165+
{
166+
"name": "Deprecated Features section",
167+
"patterns": [
168+
"##.*[Dd]eprecated",
169+
"deprecation",
170+
"features.*deprecated"
171+
],
172+
"weight": 0.15
173+
},
174+
{
175+
"name": "New Features section",
176+
"patterns": [
177+
"##.*[Nn]ew.*[Ff]eatures",
178+
"new.*capabilit",
179+
"added.*feature"
180+
],
181+
"weight": 0.15
182+
},
183+
{
184+
"name": "Migration Steps section",
185+
"patterns": [
186+
"##.*[Mm]igration.*[Ss]teps",
187+
"step.*by.*step",
188+
"upgrade.*steps"
189+
],
190+
"weight": 0.20
191+
},
192+
{
193+
"name": "Testing section",
194+
"patterns": [
195+
"##.*[Tt]est",
196+
"validation",
197+
"verify.*migration"
198+
],
199+
"weight": 0.10
200+
},
201+
{
202+
"name": "Rollback section",
203+
"patterns": [
204+
"##.*[Rr]ollback",
205+
"revert",
206+
"downgrade"
207+
],
208+
"weight": 0.05
209+
}
210+
]
211+
}
212+
},
213+
"pass_threshold": 0.7,
214+
"metadata": {
215+
"old_version": "v1.30.0",
216+
"new_version": "v1.31.0",
217+
"focus_component": "External Processing (ext_proc) HTTP filter",
218+
"proto_path": "api/envoy/extensions/filters/http/ext_proc/v3/",
219+
"impl_path": "source/extensions/filters/http/ext_proc/"
220+
}
221+
}

0 commit comments

Comments
 (0)