Problem

Backport operations frequently fail due to merge conflicts in version-specific files:

1. docs/release-notes/* - Version-specific files that differ between main and release branches (e.g., 11.0.0.md on main vs 10.4.0.md on release branches)
2. eng/common/* - Shared engineering tooling that may have version-specific differences

Example failure:

$ git am --3way --empty=keep --ignore-whitespace --keep-non-patch changes.patch

Applying: Add a failsafe in case of infinite types
Applying: do not cache when invalid keys
Applying: refactor
Applying: rn
.git/rebase-apply/patch:13: trailing whitespace.
* Type relations cache: handle potentially "infinite" types ([PR #19010](https://github.com/dotnet/fsharp/pull/19010))  
warning: 1 line adds whitespace errors.
Using index info to reconstruct a base tree...
M	docs/release-notes/.FSharp.Compiler.Service/11.0.0.md
Falling back to patching base and 3-way merge...
Auto-merging docs/release-notes/.FSharp.Compiler.Service/11.0.0.md
CONFLICT (content): Merge conflict in docs/release-notes/.FSharp.Compiler.Service/11.0.0.md
error: Failed to merge in the changes.

Solution

This PR updates .github/workflows/backport.yml to use the new additional_git_am_switches input from dotnet/arcade (PR dotnet/arcade#16235) to automatically exclude these problematic paths during backport operations.

Changes

Added additional_git_am_switches parameter with:

• --exclude=docs/release-notes/* - Skip version-specific release notes
• --exclude=eng/common/* - Skip shared engineering tooling
• --whitespace=fix - Automatically fix trailing whitespace issues

Updated PR description template to notify users that:

• Release notes and eng/common files are excluded from the backport
• These files should be manually added to the appropriate version file for the target branch if needed

Benefits

• ✅ Prevents automatic backport failures due to version-specific file conflicts
• ✅ Fixes whitespace errors that cause warnings
• ✅ Maintains clarity by documenting exclusions in the PR description
• ✅ Allows release notes to be manually added with correct version numbers for the target branch

Dependencies

This change depends on dotnet/arcade#16235 being merged, which adds the additional_git_am_switches input to the backport workflow.

Testing

Once dotnet/arcade#16235 is available, this can be tested with:

1. A PR that modifies only code (should backport cleanly)
2. A PR that modifies code + release notes (should backport code only, with note about excluded files)
3. A PR that modifies eng/common (should exclude those changes)

This pull request was created as a result of the following prompt from Copilot chat.

Problem

Backport operations frequently fail due to merge conflicts in:

1. docs/release-notes/* - Version-specific files that differ between main and release branches (e.g., 11.0.0.md on main vs 10.4.0.md on release branches)
2. eng/common/* - Shared engineering tooling that may have version-specific differences

Example failure:

$ git am --3way --empty=keep --ignore-whitespace --keep-non-patch changes.patch

Applying: Add a failsafe in case of infinite types
Applying: do not cache when invalid keys
Applying: refactor
Applying: rn
.git/rebase-apply/patch:13: trailing whitespace.
* Type relations cache: handle potentially "infinite" types ([PR #19010](https://github.com/dotnet/fsharp/pull/19010))  
warning: 1 line adds whitespace errors.
Using index info to reconstruct a base tree...
M	docs/release-notes/.FSharp.Compiler.Service/11.0.0.md
Falling back to patching base and 3-way merge...
Auto-merging docs/release-notes/.FSharp.Compiler.Service/11.0.0.md
CONFLICT (content): Merge conflict in docs/release-notes/.FSharp.Compiler.Service/11.0.0.md
error: Failed to merge in the changes.

Solution

Update .github/workflows/backport.yml to use the new additional_git_am_switches input from dotnet/arcade (PR #16235) to automatically exclude these problematic paths during backport operations.

Implementation

Modify .github/workflows/backport.yml:

Add the additional_git_am_switches input to exclude both directories and fix whitespace issues:

jobs:
  backport:
    if: ${{ contains(github.event.comment.body, '/backport to') || github.event_name == 'schedule' }}
    uses: dotnet/arcade/.github/workflows/backport-base.yml@main
    with:
      additional_git_am_switches: '--exclude=docs/release-notes/* --exclude=eng/common/* --whitespace=fix'
      pr_description_template: |
        Backport of #%source_pr_number% to %target_branch%

        /cc %cc_users%

        **Note:** Release notes and `eng/common` files are excluded from this backport. If release notes are needed, they should be added manually to the appropriate version file for this branch.

        ## Customer Impact

        ## Testing

        ## Risk

        IMPORTANT: Is this backport for a servicing release? If so and this change touches code that ships in a NuGet package, please make certain that you have added any necessary [package authoring]...

Changes Summary

1. Add additional_git_am_switches parameter with:

   • --exclude=docs/release-notes/* - Skip version-specific release notes
   • --exclude=eng/common/* - Skip shared engineering tooling
   • --whitespace=fix - Automatically fix trailing whitespace issues

2. Update PR description template to note that excluded files should be handled manually if needed

Benefits

• ✅ Prevents automatic backport failures due to version-specific file conflicts
• ✅ Fixes whitespace errors that cause warnings
• ✅ Maintains clarity by documenting exclusions in the PR description
• ✅ Allows release notes to be manually added with correct version numbers for the target branch

Testing

This change depends on dotnet/arcade#16235 being merged. Once available, test with:

1. A PR that modifies only code (should backport cleanly)
2. A PR that modifies code + release notes (should backport code only)
3. A PR that modifies eng/common (should exclude those changes)

Related

• Depends on: Add additional_git_am_switches input to backport workflow for handling branch-specific files arcade#16235
• Solves: Recurring backport failures in dotnet/fsharp related to release notes conflicts

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.