Porting changes between branches
Before porting
- Identify the source branch, target branch, and reason for the port.
- Read the branch guide.
- If either branch is a release branch, use
pwsh eng/Get-ReleaseBranches.ps1 to identify it. Do not assume main is the current release branch.
- Compare branch history, source PRs, and final patches. A different commit may already provide the same change on the target.
- Identify the logical changes and their dependencies. Include only changes that belong on the target.
Use these common directions as a guide:
| Direction |
Port when |
nightly to release/* |
A change in nightly is planned to be shipped in the next release. This is the most common porting operation. Exclude daily-only version bumps, experiments, and changes already represented on the release branch. |
release/* to main |
The release contents are final and will be published soon. |
main to nightly |
After a new .NET release, use the merge-main-to-nightly skill to merge changes from main into nightly. Outside of normal release processes, individual changes may be ported as needed if a fix was made initially in the main branch instead of the nightly branch. |
nightly to main |
A fix in the nightly branch affects all currently published images, shared automation, tests, samples, or documentation before the next release merge. |
main to release/* |
main had changes after the release branch was created. Example: new Aspire Dashboard version. |
release/* to nightly |
Rare. Prefer the normal release/* to main to nightly route. Port directly only when nightly needs an urgent fix before that route completes. |
Version-only daily or preview updates stay on nightly, except when that exact preview version is being published or when those updates include meaningful changes beyond just versions (Dockerfile changes, test changes, etc.).
Security, correctness, and release-blocking fixes may take priority over the normal cadence.
Choosing an integration method
- The default flow is to cherry-pick the final (squashed or merged) commits for each change/PR directly from the source branch.
- If the change does not apply cleanly, confirm the expected behavior with the user. The change may require extra work to preserve the user's intention.
Applying changes
- Base new work on the target branch.
- Preserve product versions, publishing settings, and other state that intentionally differs on the target.
- Follow the
resolving-conflicts skill when a cherry-pick or merge has conflicts.
- Regenerate Dockerfiles, READMEs, and test baselines after changing their inputs.
Completing the port
- Review the complete target diff and run focused validation.
- Get user confirmation before submitting a pull request.
- Open a pull request using the template.
1---2name: porting-changes3description: Plan and move changes between branches in dotnet/dotnet-docker. Use when asked to port or backport changes.4---56# Porting changes between branches78## Before porting910- Identify the source branch, target branch, and reason for the port.11- Read the [branch guide](../../../eng/developer-docs/branches.md).12- If either branch is a release branch, use `pwsh eng/Get-ReleaseBranches.ps1` to identify it. Do not assume `main` is the current release branch.13- Compare branch history, source PRs, and final patches. A different commit may already provide the same change on the target.14- Identify the logical changes and their dependencies. Include only changes that belong on the target.1516Use these common directions as a guide:1718| Direction | Port when |19| --- | --- |20| `nightly` to `release/*` | A change in nightly is planned to be shipped in the next release. This is the most common porting operation. Exclude daily-only version bumps, experiments, and changes already represented on the release branch. |21| `release/*` to `main` | The release contents are final and will be published soon. |22| `main` to `nightly` | After a new .NET release, use the `merge-main-to-nightly` skill to merge changes from `main` into `nightly`. Outside of normal release processes, individual changes may be ported as needed if a fix was made initially in the `main` branch instead of the `nightly` branch. |23| `nightly` to `main` | A fix in the `nightly` branch affects all currently published images, shared automation, tests, samples, or documentation before the next release merge. |24| `main` to `release/*` | `main` had changes after the release branch was created. Example: new Aspire Dashboard version. |25| `release/*` to `nightly` | Rare. Prefer the normal `release/*` to `main` to `nightly` route. Port directly only when nightly needs an urgent fix before that route completes. |2627Version-only daily or preview updates stay on `nightly`, except when that exact preview version is being published or when those updates include meaningful changes beyond just versions (Dockerfile changes, test changes, etc.).28Security, correctness, and release-blocking fixes may take priority over the normal cadence.2930## Choosing an integration method3132- The default flow is to cherry-pick the final (squashed or merged) commits for each change/PR directly from the source branch.33- If the change does not apply cleanly, confirm the expected behavior with the user. The change may require extra work to preserve the user's intention.3435## Applying changes3637- Base new work on the target branch.38- Preserve product versions, publishing settings, and other state that intentionally differs on the target.39- Follow the `resolving-conflicts` skill when a cherry-pick or merge has conflicts.40- Regenerate Dockerfiles, READMEs, and test baselines after changing their inputs.4142## Completing the port43441. Review the complete target diff and run focused validation.452. Get user confirmation before submitting a pull request.463. Open a pull request using the [template](./reference/pull-request-template.md).
.NET (Microsoft)