From adb278a4ff3b13a31a63a6ead42a49e0eaba674c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Dinis=20Ferreira?= Date: Mon, 6 Jul 2026 12:38:59 +0100 Subject: [PATCH] docs: adopt two-step rename+translate commit structure in xtend-to-java skill Replace the single-commit rule with a rename -> translate structure: a pure git-mv commit (100% similarity, so git log --follow and blame permanently traverse the migration boundary) followed by an in-place translate commit (guaranteed side-by-side Xtend-vs-Java diff on the PR Commits tab), plus the existing infrastructure-cleanup commit when a module goes fully off Xtend. Documents the accepted trade-offs: the rename commit intentionally does not compile (one bisect-skip on master after rebase-merge), and the aggregate Files-changed tab pairing is unaffected by commit structure (it depends only on end-state content similarity). Co-Authored-By: Claude Opus 4.8 --- .../workflow/formatting-and-commit.md | 46 ++++++++++++++----- .../workflow/multi-file-batch.md | 8 ++-- .../workflow/validation-checklist.md | 2 +- 3 files changed, 40 insertions(+), 16 deletions(-) diff --git a/.agents/skills/xtend-to-java/workflow/formatting-and-commit.md b/.agents/skills/xtend-to-java/workflow/formatting-and-commit.md index c364710e92..33ea532fd7 100644 --- a/.agents/skills/xtend-to-java/workflow/formatting-and-commit.md +++ b/.agents/skills/xtend-to-java/workflow/formatting-and-commit.md @@ -65,22 +65,44 @@ Select all migrated files in Package Explorer → Source → Format. Then amend The Eclipse formatter re-indents text block content AND closing `"""` together, preserving indent stripping semantics. Formatted text blocks produce the same string values as unformatted ones — the formatter is safe for text blocks. -## Commit structure - -**One single commit** containing everything: -- Migrated `.java` files -- Deleted `.xtend` originals -- Deleted `xtend-gen/` directory (if module fully off Xtend) -- All infrastructure changes (MANIFEST.MF, build.properties, .classpath, .project) - -Do not split into multiple commits. +## Commit structure — two-step rename → translate + +Structure every migration slice as **two commits plus an optional infrastructure commit**: + +1. **Rename commit** — a pure `git mv` of every `.xtend` in the slice to `.java`, content + **unchanged**. Because the rename edge has 100% content similarity, Git's rename detection + always traverses it: `git log --follow` and `git blame` permanently connect the `.java` + history to its `.xtend` past. (Git stores no rename metadata — a combined delete+add commit + only keeps history if the finished Java stays >50% similar to the Xtend source, which heavy + rewrites don't.) +2. **Translate commit** — rewrite the renamed files **in place** to the final Java. Reviewers + get a side-by-side Xtend-vs-Java diff per file on the PR's Commits tab (the paths are + unchanged, so the pairing is guaranteed regardless of similarity). Put the per-file + faithfulness notes (null-semantics decisions, documented deviations) in this commit's body. +3. **Infrastructure commit** (only when the module is now fully off Xtend) — the + [`infrastructure-cleanup.md`](./infrastructure-cleanup.md) changes: build.properties, + .classpath, .project, `xtend-gen/` deletion, MANIFEST check. + +Known trade-offs (accepted): +- The rename commit **intentionally does not compile** (Xtend syntax in `.java` files). PR CI + only builds the head, so CI stays green; after a rebase-merge the intermediate commit costs + one `git bisect skip` on master. +- The aggregate **Files-changed tab is unaffected** by the commit structure: it diffs + base…head and pairs old/new only when end-state similarity crosses Git's threshold. + Near-transliterations pair either way; heavy rewrites pair under neither. Point reviewers to + the Commits tab for the guaranteed in-place diff. + +Do not split the translate step per file — every intermediate commit before the last file +would be broken anyway, so per-file translate commits only multiply the broken range. ## Commit message format ``` -refactor: migrate Xtend to Java - +refactor: migrate Xtend to Java - (1/2: rename sources) +refactor: migrate Xtend to Java - (2/2: translate to Java 21) +refactor: drop Xtend build infrastructure from # when applicable ``` -Example: `refactor: migrate Xtend to Java - com.avaloq.tools.ddk.check.core.test` +The rename commit body must state that it is a pure `git mv` and intentionally non-compiling. -PR title: same as commit message. +PR title: `refactor: migrate Xtend to Java - `. diff --git a/.agents/skills/xtend-to-java/workflow/multi-file-batch.md b/.agents/skills/xtend-to-java/workflow/multi-file-batch.md index add7590e45..72dc1d0699 100644 --- a/.agents/skills/xtend-to-java/workflow/multi-file-batch.md +++ b/.agents/skills/xtend-to-java/workflow/multi-file-batch.md @@ -42,12 +42,14 @@ A red gate means you do not start the next batch. Diagnose first. ### Commit structure -**One single commit per module** containing everything: migrated Java files, deleted `.xtend` -originals, deleted `xtend-gen/` directory (if module is fully off Xtend), and all infrastructure changes. +**Two-step rename → translate per module** (see [`formatting-and-commit.md`](./formatting-and-commit.md)): +a pure `git mv` rename commit for all `.xtend` in the slice, an in-place translate commit, and — +when the module is fully off Xtend — an infrastructure-cleanup commit. Commit message format: ``` -refactor: migrate Xtend to Java - +refactor: migrate Xtend to Java - (1/2: rename sources) +refactor: migrate Xtend to Java - (2/2: translate to Java 21) ``` Example: `refactor: migrate Xtend to Java - com.avaloq.tools.ddk.check.core.test` diff --git a/.agents/skills/xtend-to-java/workflow/validation-checklist.md b/.agents/skills/xtend-to-java/workflow/validation-checklist.md index 04f8773524..18cc88fc0a 100644 --- a/.agents/skills/xtend-to-java/workflow/validation-checklist.md +++ b/.agents/skills/xtend-to-java/workflow/validation-checklist.md @@ -83,7 +83,7 @@ Run through this list before declaring a conversion done. Every item is a hard g | # | Rule | Requirement | |---|------|-------------| | 21 | Copyright headers | File starts with the exact Avaloq `/**…**/` banner header (see [`formatting-and-commit.md`](./formatting-and-commit.md)). This **replaces** any header the source carried — a `/* generated by Xtext x.y */` stub marker or a `/** … */` Javadoc-style copyright block. Normalising to the banner is **not** "inventing" (rule 1 does not apply to the copyright header). Match a sibling `.java` in the module. | -| 22 | Commit format | `refactor: migrate Xtend to Java - `. Single commit. | +| 22 | Commit format | Two-step: `(1/2: rename sources)` pure `git mv` commit + `(2/2: translate to Java 21)` in-place rewrite commit (+ infra commit when module fully off Xtend). See [`formatting-and-commit.md`](./formatting-and-commit.md). | | 28 | Infrastructure cleanup | Remove Xtend from MANIFEST.MF, build.properties, .classpath, .project; delete `xtend-gen/` directory (when module fully off Xtend). | ### Migration-campaign gates (learned)