From 2f910d240317badc3592758621178efceb51afb1 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Tue, 18 Nov 2025 13:21:43 -0800 Subject: [PATCH 1/6] update transport version documentation --- docs/internal/Versioning.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/internal/Versioning.md b/docs/internal/Versioning.md index 569982a2e4cbd..a380edd67e348 100644 --- a/docs/internal/Versioning.md +++ b/docs/internal/Versioning.md @@ -110,8 +110,25 @@ needed to backport to `8.19` you would run (in `main`): ./gradlew generateTransportVersion --name=my_tv --backport-branches=9.1,8.19 In the above case CI will not know what transport version name to update, so you -must run the generate task again as described. After merging the updated transport -version it will need to be backported to all the applicable branches. +must run the generate task again as described. After merging the updated +transport version it will need to be backported to all the applicable branches. +Backport branches that already included the original change can use +auto-backport in CI or cherry-pick the new transport version change. Backport +branches that did not include the original change need to cherry-pick both the +original change and the new transport version change. Summarized steps: + +1. Generate and merge the change with a newly created transport version to +`main` with a backport branch of `9.1` +2. Use auto-backport from CI to merge change with the newly created transport +version into `9.1` +3. Discover it's necessary for this change to be backported to `8.19` +4. Generate and merge a change to add a transport version for `8.19` into `main` +and the backport branch `9.1` that already has the original change using +auto-backport in CI +5. Cherry-pick both the original change and the change for the additional +transport version for `8.19` into a new backport branch +6. Create a new pull request for this backport branch for `8.19` and merge +once CI passes ### Resolving merge conflicts From b88f78a5ca4249c69cba5238da1486a842387180 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 19 Nov 2025 08:00:16 -0800 Subject: [PATCH 2/6] update docs based on pr feedback --- docs/internal/Versioning.md | 37 +++++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 14 deletions(-) diff --git a/docs/internal/Versioning.md b/docs/internal/Versioning.md index a380edd67e348..a3a56eac9a3ab 100644 --- a/docs/internal/Versioning.md +++ b/docs/internal/Versioning.md @@ -115,20 +115,29 @@ transport version it will need to be backported to all the applicable branches. Backport branches that already included the original change can use auto-backport in CI or cherry-pick the new transport version change. Backport branches that did not include the original change need to cherry-pick both the -original change and the new transport version change. Summarized steps: - -1. Generate and merge the change with a newly created transport version to -`main` with a backport branch of `9.1` -2. Use auto-backport from CI to merge change with the newly created transport -version into `9.1` -3. Discover it's necessary for this change to be backported to `8.19` -4. Generate and merge a change to add a transport version for `8.19` into `main` -and the backport branch `9.1` that already has the original change using -auto-backport in CI -5. Cherry-pick both the original change and the change for the additional -transport version for `8.19` into a new backport branch -6. Create a new pull request for this backport branch for `8.19` and merge -once CI passes +original change and the new transport version change. For example with the above +change that is first backported to `9.1`, and subsequently added to `8.19`, the +sequence of events would look like the following: + +1. Create a pull request with target branch `main` for a new change +(`C0`) with a newly created transport version (`TV0`) required by `C0` + 1. Use the `github` labels `auto-backport` and `branch:9.1` to backport `C0` + and `TV0` into the target branch `9.1`. +2. Discover that `C0` is also required in target branch `8.19`. +3. Create a pull request with target branch `main` for a change (`C1`) to only +update `TV0` (`TV1`) for `8.19` + 1. Use the gradle task + `./gradlew generateTransportVersion --name=my_tv + --backport-branches=9.1,8.19` + to update `TV0` (`TV1`) to include `8.19` + 2. Use the `github` labels `auto-backport` and `branch:9.1`, `branch:8.19` to + backport `C1` and `TV1` into the target branches `9.1` and `8.19`. This + creates a source branch for `8.19` (`SB819`) that does not contain `C0`. + 3. Cherry-pick `C0` into the source branch `SB819` + +Note there are several ways to do potentially do each of these steps. This +specific example takes advantage of the available CI tooling to simplify the +process. ### Resolving merge conflicts From 844714d5eae29a1c35fc528e282e746ef45e794d Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 19 Nov 2025 09:51:04 -0800 Subject: [PATCH 3/6] Update docs/internal/Versioning.md Co-authored-by: Ryan Ernst --- docs/internal/Versioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/internal/Versioning.md b/docs/internal/Versioning.md index a3a56eac9a3ab..f4c0e73356d1f 100644 --- a/docs/internal/Versioning.md +++ b/docs/internal/Versioning.md @@ -135,7 +135,7 @@ update `TV0` (`TV1`) for `8.19` creates a source branch for `8.19` (`SB819`) that does not contain `C0`. 3. Cherry-pick `C0` into the source branch `SB819` -Note there are several ways to do potentially do each of these steps. This +Note there are several ways to achieve the desired end state. This specific example takes advantage of the available CI tooling to simplify the process. From 0606d44b813ed06d0173566daab5b9701b7b8fcc Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 19 Nov 2025 09:51:16 -0800 Subject: [PATCH 4/6] Update docs/internal/Versioning.md Co-authored-by: Ryan Ernst --- docs/internal/Versioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/internal/Versioning.md b/docs/internal/Versioning.md index f4c0e73356d1f..7264cf6a850ed 100644 --- a/docs/internal/Versioning.md +++ b/docs/internal/Versioning.md @@ -113,7 +113,7 @@ In the above case CI will not know what transport version name to update, so you must run the generate task again as described. After merging the updated transport version it will need to be backported to all the applicable branches. Backport branches that already included the original change can use -auto-backport in CI or cherry-pick the new transport version change. Backport +auto-backport in CI or cherry-pick the updated transport version. Backport branches that did not include the original change need to cherry-pick both the original change and the new transport version change. For example with the above change that is first backported to `9.1`, and subsequently added to `8.19`, the From c69120f8e5051779928624483c7b26eaab9ce64a Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 19 Nov 2025 09:51:27 -0800 Subject: [PATCH 5/6] Update docs/internal/Versioning.md Co-authored-by: Ryan Ernst --- docs/internal/Versioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/internal/Versioning.md b/docs/internal/Versioning.md index 7264cf6a850ed..49ecabdababba 100644 --- a/docs/internal/Versioning.md +++ b/docs/internal/Versioning.md @@ -115,7 +115,7 @@ transport version it will need to be backported to all the applicable branches. Backport branches that already included the original change can use auto-backport in CI or cherry-pick the updated transport version. Backport branches that did not include the original change need to cherry-pick both the -original change and the new transport version change. For example with the above +original change and the updated transport version. For example, with the above change that is first backported to `9.1`, and subsequently added to `8.19`, the sequence of events would look like the following: From e073d8e75fe5fa34b47b7ba7a1ce3f523dff4944 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Wed, 19 Nov 2025 09:57:31 -0800 Subject: [PATCH 6/6] update docs based on pr feedback --- docs/internal/Versioning.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/internal/Versioning.md b/docs/internal/Versioning.md index 49ecabdababba..583602166db6e 100644 --- a/docs/internal/Versioning.md +++ b/docs/internal/Versioning.md @@ -120,19 +120,19 @@ change that is first backported to `9.1`, and subsequently added to `8.19`, the sequence of events would look like the following: 1. Create a pull request with target branch `main` for a new change -(`C0`) with a newly created transport version (`TV0`) required by `C0` +(`C0`) with a newly created transport version (`TV`) required by `C0` 1. Use the `github` labels `auto-backport` and `branch:9.1` to backport `C0` - and `TV0` into the target branch `9.1`. + and `TV` into the target branch `9.1`. 2. Discover that `C0` is also required in target branch `8.19`. 3. Create a pull request with target branch `main` for a change (`C1`) to only -update `TV0` (`TV1`) for `8.19` +update `TV` to include `8.19` 1. Use the gradle task `./gradlew generateTransportVersion --name=my_tv --backport-branches=9.1,8.19` - to update `TV0` (`TV1`) to include `8.19` - 2. Use the `github` labels `auto-backport` and `branch:9.1`, `branch:8.19` to - backport `C1` and `TV1` into the target branches `9.1` and `8.19`. This - creates a source branch for `8.19` (`SB819`) that does not contain `C0`. + to update `TV` to include `8.19` + 2. Use the `github` labels `auto-backport`, `branch:9.1`, and `branch:8.19` + to backport `C1` and updated `TV` into the target branches `9.1` and `8.19`. + This creates a source branch for `8.19` (`SB819`) that does not contain `C0`. 3. Cherry-pick `C0` into the source branch `SB819` Note there are several ways to achieve the desired end state. This