From a7c93fda42e7ba199401870a14f92371cb1dd0ad Mon Sep 17 00:00:00 2001 From: Grant Spence Date: Fri, 9 Jan 2026 21:12:47 -0500 Subject: [PATCH 1/9] UPSTREAM: : openshift: Remove OWNERS.md file The OWNERS.md documentation duplicates information already maintained in the OWNERS file itself. The OWNERS file is the source of truth for maintainer information and is automatically parsed by tooling, making a separate markdown documentation file unnecessary. --- carry_consolidation/OWNERS.md | 58 ----------------------------------- 1 file changed, 58 deletions(-) delete mode 100644 carry_consolidation/OWNERS.md diff --git a/carry_consolidation/OWNERS.md b/carry_consolidation/OWNERS.md deleted file mode 100644 index 8972d1fe59..0000000000 --- a/carry_consolidation/OWNERS.md +++ /dev/null @@ -1,58 +0,0 @@ -# OWNERS carry instructions - -Our downstream fork keeps its own `OWNERS` file so the OpenShift DNS/APISnoop -teams can self-serve reviews and hook into the component automation. Upstream -CoreDNS does not ship this metadata, so every rebase needs to restore it. - -## Files to stage together -- `OWNERS` – the downstream file shown below (unchanged from - `a82419240`/`c6cbe9feb`). -- `.ci-operator.yaml`, `Dockerfile.ocp`, `Dockerfile.openshift` – carried in the - automation metadata commit, but listed here so reviewers know why the same set - of people remain approvers. - -## Reapply steps -1. Copy the snippet into the repo root as `OWNERS` (overwriting any upstream - placeholder): - -```yaml -approvers: - - knobunc - - Miciah - - frobware - - candita - - rfredette - - alebedev87 - - gcs278 - - rikatz - -component: DNS - -features: - - comments - - reviewers - - aliases - - branches - - exec - -aliases: - - | - /plugin: (.*) -> /label add: plugin/$1 - - | - /approve -> /lgtm - - | - /wai -> /label add: works as intended - - | - /release: (.*) -> /exec: /opt/bin/release-coredns $1 -``` - -2. Run `git add OWNERS` (or `git checkout --theirs OWNERS` when resolving - conflicts). -3. Commit as part of `UPSTREAM: : openshift: restore automation metadata` - so the OWNERS/automation files travel together and reviewers have a single - place to look. - -Historical context: this file originated in commits like `a82419240` and was -last reviewed by @Miciah and @alebedev87. Keeping the instructions in Markdown -instead of raw patch form makes it easier to see what the carry reintroduces -without having to consult the archived rebase report. From 28fd978cf4b7cc89e22e171848925b8648b1bc49 Mon Sep 17 00:00:00 2001 From: Grant Spence Date: Fri, 9 Jan 2026 21:04:44 -0500 Subject: [PATCH 2/9] UPSTREAM: : openshift: Move dependabot_policy.md to openshift-rebase/carries/ --- .../carries}/dependabot_policy.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {carry_consolidation => openshift-rebase/carries}/dependabot_policy.md (100%) diff --git a/carry_consolidation/dependabot_policy.md b/openshift-rebase/carries/dependabot_policy.md similarity index 100% rename from carry_consolidation/dependabot_policy.md rename to openshift-rebase/carries/dependabot_policy.md From f57284f57d3bd60d15014dfdbf37b640d56e02d3 Mon Sep 17 00:00:00 2001 From: Grant Spence Date: Fri, 9 Jan 2026 21:08:32 -0500 Subject: [PATCH 3/9] UPSTREAM: : openshift: Remove gitignore.patch and update .gitignore Remove gitignore.patch file as it duplicates information already captured in the git commit itself. Since git commits inherently contain diffs, maintaining a separate .patch file is unnecessary. The commit history provides the same information and remains the source of truth for the changes. Also add .claude/settings.local.json to .gitignore as it contains user-specific settings. --- .gitignore | 1 + carry_consolidation/gitignore.patch | 19 ------------------- 2 files changed, 1 insertion(+), 19 deletions(-) delete mode 100644 carry_consolidation/gitignore.patch diff --git a/.gitignore b/.gitignore index be6fd2f04b..643df72f86 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ coredns.exe Corefile /build/ release/ +.claude/settings.local.json diff --git a/carry_consolidation/gitignore.patch b/carry_consolidation/gitignore.patch deleted file mode 100644 index b12cfc7abf..0000000000 --- a/carry_consolidation/gitignore.patch +++ /dev/null @@ -1,19 +0,0 @@ -diff --git a/.gitignore b/.gitignore -index 5a6dd1245..bd3896f72 100644 ---- a/.gitignore -+++ b/.gitignore -@@ -1,7 +1,7 @@ --# only add build artifacts concerning coredns - no editor related files --coredns --coredns.exe --Corefile --build/ --release/ --vendor/ -+query.log -+Corefile -+*.swp -+/coredns -+coredns.exe -+/build/ -+release/ From f25314d8fc6e4014c372b9f88e7af313b5965896 Mon Sep 17 00:00:00 2001 From: Grant Spence Date: Fri, 9 Jan 2026 21:08:37 -0500 Subject: [PATCH 4/9] UPSTREAM: : openshift: Move make_test_policy.md to openshift-rebase/carries/ --- .../carries}/make_test_policy.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {carry_consolidation => openshift-rebase/carries}/make_test_policy.md (100%) diff --git a/carry_consolidation/make_test_policy.md b/openshift-rebase/carries/make_test_policy.md similarity index 100% rename from carry_consolidation/make_test_policy.md rename to openshift-rebase/carries/make_test_policy.md From bef62f00abd9fb655aaa78d98a9ecb3658d95e1d Mon Sep 17 00:00:00 2001 From: Grant Spence Date: Fri, 9 Jan 2026 21:08:42 -0500 Subject: [PATCH 5/9] UPSTREAM: : openshift: Remove makefile.patch file The patch file duplicates information already captured in the git commit itself. Since git commits inherently contain diffs, maintaining a separate .patch file is unnecessary. The commit history provides the same information and remains the source of truth for the changes. --- carry_consolidation/makefile.patch | 14 -------------- 1 file changed, 14 deletions(-) delete mode 100644 carry_consolidation/makefile.patch diff --git a/carry_consolidation/makefile.patch b/carry_consolidation/makefile.patch deleted file mode 100644 index c1bce71a27..0000000000 --- a/carry_consolidation/makefile.patch +++ /dev/null @@ -1,14 +0,0 @@ -diff --git a/Makefile b/Makefile -index 6d8cd9189..98a5bc3d3 100644 ---- a/Makefile -+++ b/Makefile -@@ - .PHONY: test --test: check -- ( cd request ; go test -v -race ./... ) -- ( cd core ; go test -v -race ./... ) -- ( cd coremain ; go test -v -race ./... ) -- ( cd test ; go test -v -race ./... ) -- ( cd plugin ; go test -v -race ./... ) -+test: check -+ GOFLAGS=-mod=vendor go test -count=1 ./... From 668bde22a9ac85eb7ccdd0892a1bc11cd2c4649a Mon Sep 17 00:00:00 2001 From: Grant Spence Date: Fri, 9 Jan 2026 21:08:46 -0500 Subject: [PATCH 6/9] UPSTREAM: : openshift: Move ocp_dnsnameresolver.md to openshift-rebase/carries/ --- .../carries}/ocp_dnsnameresolver.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {carry_consolidation => openshift-rebase/carries}/ocp_dnsnameresolver.md (100%) diff --git a/carry_consolidation/ocp_dnsnameresolver.md b/openshift-rebase/carries/ocp_dnsnameresolver.md similarity index 100% rename from carry_consolidation/ocp_dnsnameresolver.md rename to openshift-rebase/carries/ocp_dnsnameresolver.md From d894fb245cf9252af8639cef43d00da59018d11a Mon Sep 17 00:00:00 2001 From: Grant Spence Date: Fri, 9 Jan 2026 21:08:52 -0500 Subject: [PATCH 7/9] UPSTREAM: : openshift: Move and update vendor_workflow.md Move to openshift-rebase/carries/ and update commit ordering language from 'LAST' to 'towards the end' to accommodate drop commits. --- carry_consolidation/vendor_workflow.md | 17 -------- openshift-rebase/carries/vendor_workflow.md | 44 +++++++++++++++++++++ 2 files changed, 44 insertions(+), 17 deletions(-) delete mode 100644 carry_consolidation/vendor_workflow.md create mode 100644 openshift-rebase/carries/vendor_workflow.md diff --git a/carry_consolidation/vendor_workflow.md b/carry_consolidation/vendor_workflow.md deleted file mode 100644 index f1a52e78ec..0000000000 --- a/carry_consolidation/vendor_workflow.md +++ /dev/null @@ -1,17 +0,0 @@ -## Downstream vendoring strategy - -We continue to vendor dependencies so downstream builds do not rely on network access. - -### Regenerating vendor after the rebase -1. Ensure `go.mod` and `go.sum` reflect the desired dependency set (run `go mod tidy` if needed once conflicts are resolved). -2. Run `GOFLAGS=-mod=vendor go mod vendor` (or export `GOFLAGS=-mod=vendor` globally) to repopulate `vendor/`. -3. Re-apply the downstream ginkgo shim (`vendor/github.com/onsi/ginkgo/v2/ginkgo/build/build_command.go`) if it is dropped by `go mod vendor`. -4. Stage the entire `vendor/` tree along with `go.mod` / `go.sum` updates in a single carry commit. - -### Build tooling expectations -- Dockerfiles (`Dockerfile.openshift`, `Dockerfile.openshift.rhel7`, etc.) must keep `GO111MODULE=on` and `GOFLAGS=-mod=vendor` so container builds consume the vendored tree. -- Any CI/Make targets that compile CoreDNS should set `GOFLAGS=-mod=vendor` (unless the buildroot already enforces it). - -### .gitignore adjustments -- Keep vendor tracked by removing the upstream `vendor/` ignore entry; see `carry_consolidation/gitignore.patch`. -- Ignore build outputs only: `query.log`, `Corefile`, `*.swp`, `/coredns`, `coredns.exe`, `/build/`, `release/`. diff --git a/openshift-rebase/carries/vendor_workflow.md b/openshift-rebase/carries/vendor_workflow.md new file mode 100644 index 0000000000..894aab19cf --- /dev/null +++ b/openshift-rebase/carries/vendor_workflow.md @@ -0,0 +1,44 @@ +## Downstream vendoring strategy + +We continue to vendor dependencies so downstream builds do not rely on network access. + +### Carry Commit Strategy + +**IMPORTANT**: The vendor carry commit is cherry-picked like other carries, but must be **regenerated** after cherry-picking because the vendored dependencies change with each upstream version. Run `go mod tidy && go mod vendor` and amend the commit with the updated vendor tree. + +**CRITICAL - Only One Vendor Commit**: +There should be **only one** vendor carry commit in the final rebase, positioned **towards the end** of carry commits. If multiple vendor commits exist after cherry-picking (e.g., from intermediate carries or conflicts), squash them into a single vendor commit using `git rebase -i`, then regenerate the vendor tree to capture the complete dependency state. + +### Moving Vendor Commit to the End + +After cherry-picking all carries and adding any new carries, the vendor commit needs to be at the end before regenerating: + +```bash +# Find the merge helper commit +MERGE_HELPER=$(git log --oneline --merges --grep="rebase-to-v" -1 --format="%H") + +# Move the vendor commit to be the last commit +git rebase -i ${MERGE_HELPER} +# In the editor, move the "vendor deps" commit line to the bottom of the list +# Save and exit + +# Now regenerate and amend the vendor commit +go mod tidy && go mod vendor +git add vendor/ go.mod go.sum +git commit --amend --no-edit +``` + +**Key principle**: The vendor commit must be at HEAD when you regenerate it, so you can use `git commit --amend`. + +### Regenerating vendor after the rebase +1. Ensure `go.mod` and `go.sum` reflect the desired dependency set (run `go mod tidy` if needed once conflicts are resolved). +2. Run `GOFLAGS=-mod=vendor go mod vendor` (or export `GOFLAGS=-mod=vendor` globally) to repopulate `vendor/`. +3. Stage the entire `vendor/` tree along with `go.mod` / `go.sum` updates in a single carry commit with `UPSTREAM: : openshift:` prefix. + +### Build tooling expectations +- Dockerfiles (`Dockerfile.openshift`, `Dockerfile.openshift.rhel7`, etc.) must keep `GO111MODULE=on` and `GOFLAGS=-mod=vendor` so container builds consume the vendored tree. +- Any CI/Make targets that compile CoreDNS should set `GOFLAGS=-mod=vendor` (unless the buildroot already enforces it). + +### .gitignore adjustments +- Keep vendor tracked by removing the upstream `vendor/` ignore entry. +- Ignore build outputs only: `query.log`, `Corefile`, `*.swp`, `/coredns`, `coredns.exe`, `/build/`, `release/`. From d45d2a7a269d28c00c66d322bc7c8c5cad75e922 Mon Sep 17 00:00:00 2001 From: Grant Spence Date: Fri, 9 Jan 2026 21:08:56 -0500 Subject: [PATCH 8/9] UPSTREAM: : openshift: Add toolchain_management.md to carries/ --- .../carries/toolchain_management.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 openshift-rebase/carries/toolchain_management.md diff --git a/openshift-rebase/carries/toolchain_management.md b/openshift-rebase/carries/toolchain_management.md new file mode 100644 index 0000000000..62ce61f5be --- /dev/null +++ b/openshift-rebase/carries/toolchain_management.md @@ -0,0 +1,62 @@ +## Toolchain Management Strategy + +Downstream OpenShift builds occur in disconnected/offline environments and cannot download Go toolchains from the network. This carry commit ensures builds use whatever Go version ART provides in builder images. + +### Carry Commit Strategy + +**This is an unconditional, permanent carry commit.** Always apply it during every rebase. + +``` +UPSTREAM: : openshift: set GOTOOLCHAIN=local for offline builds +``` + +### The Problem + +Upstream CoreDNS sets: +```makefile +export GOTOOLCHAIN = go$(GOLANG_VERSION) +``` + +This expands to something like `GOTOOLCHAIN = go1.25.2` based on `.go-version`. When the Go toolchain in ART's builder image is older (e.g., 1.24.6), Go attempts to download the newer version from the network. In disconnected ART builds, this download fails. + +### The Solution + +Set `GOTOOLCHAIN = local` to tell Go: "Use whatever Go version is installed locally, do NOT attempt network downloads." + +### Reapply Instructions + +Edit `Makefile`: +```makefile +export GOSUMDB = sum.golang.org +export GOTOOLCHAIN = local +``` + +Create carry commit: +```bash +git add Makefile +git commit -m "UPSTREAM: : openshift: set GOTOOLCHAIN=local for offline builds + +ART builds occur in disconnected environments and cannot download Go +toolchains from the network. Setting GOTOOLCHAIN=local ensures builds +use whatever Go version is provided in the builder image." +``` + +### What NOT to do + +**Do NOT downgrade `.go-version`** to match ART builder versions. Keep `.go-version` at upstream's value. ART automation updates `Dockerfile.ocp` based on builder images, but does NOT touch `.go-version`. These files can (and do) diverge - that's expected and fine. + +### Validation + +```bash +# Verify build works +make + +# Verify tests pass +make test +``` + +### Related Files + +- `Makefile` - Where `GOTOOLCHAIN` is set +- `.go-version` - Upstream's Go requirement (leave at upstream value) +- `Dockerfile.ocp` - ART's builder image reference (ART automation controls this) From 380a4956ae98c33e8f65d1c3e64cf4716805437b Mon Sep 17 00:00:00 2001 From: Grant Spence Date: Fri, 9 Jan 2026 21:09:34 -0500 Subject: [PATCH 9/9] UPSTREAM: : openshift: Add /rebase slash command and documentation Add automated rebase assistant with comprehensive workflow for CoreDNS version rebases. Includes carry analysis, conflict handling, report generation, and PR creation with stakeholder review documents. Co-Authored-By: Claude Sonnet 4.5 --- .claude/commands/rebase.md | 289 ++++++++++++++++++++++++++++++ openshift-rebase/REBASE.md | 131 ++++++++++++++ openshift-rebase/reports/.gitkeep | 1 + 3 files changed, 421 insertions(+) create mode 100644 .claude/commands/rebase.md create mode 100644 openshift-rebase/REBASE.md create mode 100644 openshift-rebase/reports/.gitkeep diff --git a/.claude/commands/rebase.md b/.claude/commands/rebase.md new file mode 100644 index 0000000000..928f8aa28a --- /dev/null +++ b/.claude/commands/rebase.md @@ -0,0 +1,289 @@ +# CoreDNS Rebase Slash Command + +You are a CoreDNS rebase assistant. When invoked, you help manage and execute CoreDNS version rebases for OpenShift. + +## Workflow + +When the user invokes `/rebase`: + +### 1. Ask for Context and Explain Workflow + +**Fetch Upstream Tags**: +First, ensure upstream tags are available: +```bash +git fetch upstream --tags +``` + +**Ask Questions Individually** (one at a time, wait for response before asking next): + +1. **Target CoreDNS version**: Use AskUserQuestion with multiple choice + - Fetch recent upstream tags: `git tag -l 'v1.*' --sort=-version:refname | head -4` + - Check current version from main branch merge commit + - Present top 3-4 most recent tags as options + - Label the latest as "(Recommended)" + - Include incremental updates from current version if available + - Example options: "v1.14.0 (Recommended)", "v1.13.2" + +2. **Known concerns or blockers**: Ask as text input + - "Are there any known concerns or blockers for this rebase?" + +3. **Special instructions for carry patches**: Ask as text input + - "Do you have any special instructions for existing carry patches or new carries to add?" + +Then, explain the workflow upfront: +"I'll guide you through the rebase process with the following steps: +1. **Analyze Current State** - Review current version, carries, and dependencies +2. **Execute Rebase** - Cherry-pick carries, handle conflicts, squash commits, regenerate vendor +3. **Generate Reports** - Create comprehensive rebase report and stakeholder review document +4. **User Review** - Present summary and ask for your feedback before creating PR +5. **Create PR** - After your approval, create PR with high-level summary + +Before creating the PR, I'll present you with a summary and ask for any adjustments needed. You'll have a chance to review everything before the PR goes out." + +### 2. Analyze Current State + +**Upstream Changes**: +- Review CoreDNS release notes at `https://github.com/coredns/coredns/releases/tag/v` +- Analyze incoming changes, new features, bug fixes, deprecations +- Identify breaking changes, API migrations, dependency updates +- Assess compatibility impact on OpenShift-specific carries and plugins +- Note toolchain changes (Go version, build requirements) + +**Downstream State**: +- Read `openshift-rebase/REBASE.md` for workflow +- Check current version and carries +- Review `openshift-rebase/carries/*.md` for carry reapply instructions +- Identify all carry commits since last rebase +- Read each carry commit's description to understand the changes and context +- Analyze carry audit (classify as: still needed / already upstream / obsoleted) + +### 3. Execute the Rebase + +Follow the workflow documented in `openshift-rebase/REBASE.md`: +1. Preparation and setup +2. Cherry-pick carries (handle conflicts, skip obsolete commits) +3. Cleanup commit history (squash related commits) +4. Regenerate vendor commit +5. Build and test validation + +**IMPORTANT**: +- Record all git commands executed during the rebase for the report +- Document EVERY conflict, skip, and squash operation as they occur +- Document any explicit user feedback, guidance, or decisions provided during the rebase +- You will include all of this in Section 3: Execution Log of the final report + +### 4. Generate Complete Rebase Report + +After executing the rebase, create `openshift-rebase/reports/rebase_to_v.md` containing: + +**Section 1: Overview** +- Current CoreDNS version +- Target rebase version +- Divergence metrics (commits ahead/behind) +- Merge helper commit strategy explanation + +**Section 2: Carry Audit & Consolidation Plan** +Analyze all commits between last upstream tag and current main: + +For each commit, classify as: +- **Still needed**: Must be forward-ported +- **Already upstream**: Can be dropped (note upstream commit) +- **Obsoleted**: No longer relevant + +Include: +- Commits lacking `UPSTREAM: :` prefix that may be downstream-specific +- Consolidation recommendations (e.g., squash multiple ART commits, plugin version bumps) +- Proper commit message format with `UPSTREAM: : openshift:` prefix +- Order of carry application (vendor towards the end) + +**Section 3: Execution Log** + +Document what happened during the actual rebase execution: + +**Conflicts Resolved**: +For each conflict encountered: +- Commit: - +- Type: [modify/delete | content | rename/delete | empty] +- Resolution: [resolved | skipped] +- Details: What conflicted, action taken, reasoning + +**Skipped Commits**: +For each skipped commit: +- - +- Reason: Why it was skipped (already upstreamed, obsoleted, etc.) +- Details: Specific upstream commit or change that made this obsolete + +**Squashed Commits**: +For each squash operation: +- Into: +- Squashed: List of commits consolidated +- Reason: Why these were combined + +**User Feedback**: +Document any explicit feedback, guidance, or decisions provided by the user during the rebase: +- Timestamp/context: When the feedback was given +- Feedback: Exact user input or decision +- Action taken: How the feedback was incorporated +- Rationale: Why this approach was chosen based on user guidance + +**Section 4: Risk Assessment** +- Summary of upstream changes (brief overview from release notes) +- Breaking changes and their impact on carries +- Dependency updates and compatibility concerns (especially k8s deps for ocp_dnsnameresolver) +- Toolchain changes (Go version, build requirements) +- Testing hotspots (areas needing extra validation) +- Build/test results +- Link to stakeholder review document for detailed upstream analysis + +### 5. Generate Stakeholder Review Document + +Create `openshift-rebase/reports/rebase_v_stakeholder_review.md`: + +**Purpose**: Concise (2-3 pages) meeting agenda for pre-merge review + +**Structure**: + +**Upstream Changes Analysis** (most important section): +- Link to CoreDNS release notes: https://github.com/coredns/coredns/releases/tag/v +- New features and enhancements (what's new, why it matters for OpenShift) +- Bug fixes (especially ones affecting stability or security) +- Breaking changes and deprecations (migration required?) +- Dependency updates (k8s client libs, Go version, etc.) +- Risk assessment: High/Medium/Low for each category +- OpenShift compatibility impact (will carries still work? does ocp_dnsnameresolver need updates?) + +**Downstream Changes**: +- High-risk commits requiring discussion +- Carry consolidation summary +- External plugin status (ocp_dnsnameresolver compatibility with new deps) +- Toolchain changes needed (Go version bumps, build config) + +**Action Items**: +- Decisions needed before merge +- Testing requirements +- Owners assigned +- Space for meeting notes + +**Guidelines**: +- Upstream changes section should be most detailed (1-2 paragraphs per major change) +- Focus on impact and risk, not implementation details +- Include links (GitHub releases, upstream issues, PRs) +- Non-technical stakeholders should understand risks +- Highlight anything that needs stakeholder decision or approval + +### 6. Commit Reports with DROP Prefix + +After generating all reports, commit them with the `UPSTREAM: :` prefix: + +```bash +git add openshift-rebase/reports/ +git commit -m "UPSTREAM: : openshift: Add rebase v reports and documentation" +``` + +**Rationale**: Using `:` ensures these version-specific reports are automatically skipped in the next rebase, preventing accumulation of outdated reports across multiple rebase cycles. + +### 7. User Review and Feedback + +**IMPORTANT**: Before creating the PR, present a summary to the user and ask for review. + +Provide a concise summary with: +- Version transition (v → v) +- Stats: X carries reapplied, Y dropped, Z squashed, N conflicts resolved +- Key highlights: Major dependency changes, toolchain updates, breaking changes, etc. +- Build/test status +- Location of detailed reports + +Then ask: +- "Please review the rebase results. The detailed reports are in `openshift-rebase/reports/`. Do you have any feedback or adjustments needed before I create the PR?" +- Wait for user response +- **Document any user feedback** in the report's Section 3: Execution Log > User Feedback +- Make any requested changes to the rebase, reports, or commits +- Update the reports to reflect changes made based on feedback +- Only proceed to PR creation after user approval + +### 8. Create Pull Request + +Create a PR with a concise, high-level description. This is a **bird's eye view** summary - keep it scannable and focused on key information only. + +**PR Title**: `Rebase to CoreDNS v` + +**PR Description Structure**: + +````markdown +# Rebase to CoreDNS v + +## Summary +- **Version**: v → v +- **Carries**: X reapplied, Y dropped, Z squashed +- **Conflicts**: N resolved +- **Validation**: ✅ Build and tests passing + +## Action Plan +- ✅ Analyze current state +- ✅ Execute rebase +- ✅ Generate rebase report +- ✅ Generate stakeholder review document +- ⬜️ Stakeholder meeting +- ⬜️ CI review +- ⬜️ Peer code review +- ⬜️ OpenShift release notes + +## Commands Executed +```bash +VERSION=v +git checkout -b rebase-to-${VERSION} ${VERSION} +git merge --no-ff --strategy=ours origin/main +git cherry-pick ${MERGE_HELPER}..origin/main +# List major conflict resolutions +go mod tidy && go mod vendor +git rebase -i ${MERGE_HELPER} # Note any squashes +go build && make test +``` + +## Carries Applied (X) +- Brief list of carry commits (one-line descriptions) +- Group similar carries (e.g., "ART build configuration (squashed 3 commits)") +- Note regenerated vendor tree + +## Dropped (Y) +- List dropped commits with reason (already upstream #PR, obsoleted, etc.) + +## High Priority Review Items +- ⚠️ **Item 1**: Brief description (e.g., "Go 1.21: Toolchain bump - verify CI") +- ⚠️ **Item 2**: Brief description (e.g., "k8s deps: Updated to 0.28.x - test compatibility") +- Only include high-priority concerns that need stakeholder attention + +--- +📄 [Full Rebase Report](openshift-rebase/reports/rebase_to_v.md) | 📋 [Stakeholder Review](openshift-rebase/reports/rebase_v_stakeholder_review.md) +```` + +**Guidelines**: +- Keep descriptions concise (1 line per item) +- Focus on stats and high-level actions, not details +- Only flag high-priority concerns (breaking changes, major dependency updates, compatibility risks) +- Commands section should show actual commands run, with comments for major events +- Link to full reports at the bottom + +**After PR Creation**: +Remind the user: "The stakeholder review document (`rebase_v_stakeholder_review.md`) is intended for a peer review meeting. You can copy and paste it into a Google Doc as a starting point for discussion with your team." + +## Key References + +- **Canonical workflow**: `openshift-rebase/REBASE.md` (human instructions) +- **Carry instructions**: `openshift-rebase/carries/*.md` (detailed reapply steps) + +## Report Storage + +All reports go in `openshift-rebase/reports/`: +- `rebase_to_v.md` - Complete rebase report (includes carry audit, execution log, and action plan) +- `rebase_v_stakeholder_review.md` - Stakeholder meeting document + +## Critical Reminders + +- Merge helper comes FIRST, carries on top +- All carry commits need `UPSTREAM: : openshift:` prefix (except reports - use `:`) +- **Reports directory uses `UPSTREAM: :` prefix** - dropped each rebase to avoid accumulation +- Document all conflicts, skips, and squashes as they occur (include in Execution Log section of report) +- Read carry instructions from `openshift-rebase/carries/*.md` for guidance +- Create PR with concise bird's eye view summary - link to full reports for details +- **Stakeholder Review Document**: Remind the user that `rebase_v_stakeholder_review.md` is intended for a peer review meeting. They can copy and paste it into a Google Doc as a starting point for discussion. diff --git a/openshift-rebase/REBASE.md b/openshift-rebase/REBASE.md new file mode 100644 index 0000000000..f6f598dd8d --- /dev/null +++ b/openshift-rebase/REBASE.md @@ -0,0 +1,131 @@ +# CoreDNS Rebase Instructions + +## Overview + +OpenShift's CoreDNS fork incorporates upstream releases while maintaining downstream customizations. This document outlines the rebase process for integrating new upstream versions. + +**Note**: These instructions are intended for manual rebases. A Claude Code `/rebase` command is also available that automates much of this workflow, including report generation documentation. + +## Rebase Checklist + +Before submitting a rebase PR, verify: + +- [ ] Branch originates from upstream tag (e.g., `v1.x.y`) +- [ ] Merge helper commit created before carry patches: `git merge --no-ff --strategy=ours origin/main` +- [ ] Carry commits reapplied after merge helper with proper `UPSTREAM: : openshift:` prefix +- [ ] Vendor commit regenerated (should be towards the end of carry commits) +- [ ] Build succeeds: `go build` +- [ ] Tests pass: `make test` + +## Commit Message Format + +All downstream carry commits must use: + +``` +UPSTREAM: : openshift: +``` + +For commits that will be dropped in the next rebase: + +``` +UPSTREAM: : openshift: +``` + +For commits that cherry-pick an upstream PR: + +``` +UPSTREAM: : +``` + +Example: `UPSTREAM: 6354: Fix memory leak in cache plugin` + +This convention enables automated carry detection and is standard across OpenShift fork repositories. The prefix indicates how to handle the commit during the next rebase: +- ``: Must be reapplied/forward-ported +- ``: Skip this commit (temporary change) +- ``: Check if PR is in new upstream version; skip if already included + +## Carry Patch Documentation + +Detailed reapply instructions for specific carry types are documented in `openshift-rebase/carries/`. These documentation files are co-located in the same commits as the carries they describe, making it easy to reference the instructions when cherry-picking. + +## Rebase Workflow + +### 1. Preparation + +```bash +# Fetch upstream +git remote add upstream https://github.com/coredns/coredns.git # if needed +git fetch upstream --tags + +# Identify latest carries from the most recent rebase +# Find the merge helper commit (looks for "rebase-to-v" pattern in the most recent rebase PR) +# Example: Merge remote-tracking branch 'origin/main' into rebase-to-v1.13.2 +# NOTE: This assumes the merge helper is BEFORE carries (as documented below) +MERGE_HELPER=$(git log --oneline --merges --grep="rebase-to-v" -1 --format="%H") +git log --oneline --no-merges ${MERGE_HELPER}..origin/main +``` + +### 2. Cherry-Pick Carries + +```bash +# Set target version (e.g., v1.13.2) +VERSION=v1.x.y + +# Create branch from upstream tag +# NOTE: Do not change the branch name format 'rebase-to-v...' as it is used in the +# preparation step above to identify carry patches via the merge helper commit message +git checkout -b rebase-to-${VERSION} ${VERSION} + +# IMPORTANT: Create merge helper commit FIRST (this should be the first commit after the tag) +git merge --no-ff --strategy=ours origin/main -m "Merge remote-tracking branch 'origin/main' into rebase-to-${VERSION}" + +# Then reapply carry commits ON TOP of the merge helper +# This automatically cherry-picks all commits from the previous rebase +git cherry-pick ${MERGE_HELPER}..origin/main +``` + +**Note**: Pay attention to the `UPSTREAM:` prefix in each commit message (see Commit Message Format section above) to determine whether to cherry-pick, skip, or check upstream for PR inclusion. + +#### Handling Conflicts + +Cherry-picking will likely encounter conflicts: + +- **File deletion conflicts** (modify/delete) - Deleted files modified upstream +- **Dependency conflicts** - go.mod/go.sum conflicts (resolve then run `go mod tidy && go mod vendor`) +- **Empty commits** - Change already in upstream (skip with `git cherry-pick --skip`) +- **Vendor conflicts** - Renamed/deleted vendor files (re-run `go mod vendor` to clean up) + +### 3. Cleanup Commit History + +After cherry-picking, squash related commits to simplify the carry history: + +Common squash candidates: +- Multiple ART consistency updates → single product build config commit +- Plugin version bumps and configuration changes → initial plugin addition commit +- **Multiple vendor commits → single vendor commit** (REQUIRED - see note below) + +Use `git rebase -i ${MERGE_HELPER}` to squash commits. After squashing vendor-related changes, regenerate the vendor tree with `go mod tidy && go mod vendor` and amend the commit. + +Review final history with `git log --oneline ${MERGE_HELPER}..HEAD` and verify each commit has proper `UPSTREAM:` prefix. + +### 4. Rebuild Generated Files + +Regenerate the vendor commit (should be towards the end of carry commits). See `openshift-rebase/carries/vendor_workflow.md` for details. + +### 5. Validation + +```bash +# Build and test +go build +make test + +# Test with vendored modules +GOFLAGS=-mod=vendor go test ./... +``` + +## Post-Rebase + +1. Create PR against `main` branch +2. Document conflict resolutions and skipped commits in PR description +3. Coordinate stakeholder review for high-risk changes +4. After merge, notify relevant teams of version update diff --git a/openshift-rebase/reports/.gitkeep b/openshift-rebase/reports/.gitkeep new file mode 100644 index 0000000000..7216d2a447 --- /dev/null +++ b/openshift-rebase/reports/.gitkeep @@ -0,0 +1 @@ +# This directory contains version-specific rebase reports generated by the /rebase command