docs: add MSB3103 troubleshooting

[Copilot]

Renaming or moving a Roslyn clone breaks subsequent builds with MSB3103: Invalid Resx file … Could not find a part of the path '<OLD-PATH>\…'. The cause: XliffTasks bakes absolute ResXFileRef paths into cached translated .resx files under artifacts/obj/. MSBuild's incremental build never retriggers on a rename (timestamps unchanged), so the stale absolute paths persist.

Changes

• docs/contributing/Building, Debugging, and Testing on Windows.md — new Troubleshooting section with diagnosis, targeted fix (Remove-Item on the two stale .xlf cache dirs), the big-hammer git clean -xdf option, and a pointer to the upstream xliff-tasks fix
• docs/contributing/Building, Debugging, and Testing on Unix.md — same section adapted for Unix/macOS (rm -rf)

Upstream fix (dotnet/xliff-tasks)

The root fix is to write ResXFileRef paths relative to the translated output directory rather than absolute, so cached artifacts survive a repo rename. The one-line change in TranslateSource.cs:

// Before
sourceDocument.RewriteRelativePathsToAbsolute(Path.GetFullPath(sourcePath));

// After
sourceDocument.RewriteRelativePathsRelativeTo(Path.GetFullPath(sourcePath), translatedFullPath);

RewriteRelativePathsRelativeTo is a new virtual on TranslatableDocument (falls back to the old absolute behavior for other document types) with an override on ResxDocument that uses Path.GetRelativePath (≥.NET 5) or Uri.MakeRelativeUri on .NET Framework. The full patch with two regression tests is included in this PR description for the xliff-tasks maintainers to apply.

[azure-pipelines]

Azure Pipelines:
2 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[mwiemer-microsoft]

Still relevant as dotnet/arcade#17061 hasn't been closed yet.

[Copilot]

🟢 Approval recommended

The changes are documentation-only, and remaining feedback is limited to non-blocking cleanup warnings.

Pull request overview

Adds Windows and Unix/macOS troubleshooting guidance for MSB3103 errors caused by stale XliffTasks caches after moving a repository.

Changes:

• Documents diagnosis and targeted cache cleanup.
• Adds platform-specific recovery commands.
• References the upstream XliffTasks fix.

File summaries

File	Summary
docs/contributing/Building, Debugging, and Testing on Windows.md	Adds Windows troubleshooting guidance.
docs/contributing/Building, Debugging, and Testing on Unix.md	Adds Unix/macOS troubleshooting guidance.

Review details

Suppressed comments (2)

docs/contributing/Building, Debugging, and Testing on Unix.md:146

• git clean -xdf removes every untracked and ignored file under the repository, not just .dotnet and artifacts; this can delete local repros, configuration, or other untracked work. Please explicitly warn users to back up untracked files and verify the dry-run output before running the destructive command.

- Or, the bigger hammer: `git clean -xdn` (dry run) then `git clean -xdf`. Note this also
  deletes the locally-provisioned `.dotnet` SDK and the entire `artifacts/` tree, forcing a
  full restore + rebuild, so prefer the targeted delete above.

docs/contributing/Building, Debugging, and Testing on Windows.md:275

• git clean -xdf removes every untracked and ignored file under the repository, not just .dotnet and artifacts; this can delete local repros, configuration, or other untracked work. Please explicitly warn users to back up untracked files and verify the dry-run output before running the destructive command.

- Or, the bigger hammer, `git clean -xdfn` (dry run) then `git clean -xdf`. Note this also
  deletes the locally-provisioned `.dotnet` SDK and the entire `artifacts\` tree, forcing a
  full restore + rebuild, so prefer the targeted delete above.

• Files reviewed: 2/2 changed files
• Comments generated: 0
• Review effort level: Lite

[dibarbet]

we probably don't need two copies of this (it doesn't seem to be platform specific). Maybe keep the windows one and just link it here from unix.

[Copilot]

Done in 920da00 — the detailed section now lives only in the Windows doc, and the Unix doc links to it.

[dibarbet]

I wonder if we need so much info here. Feels like we should make this a bit more generic. Like in general if you hit weird build issues, its a good idea to wipe the artifacts folder, and then if that doesn't work do a git clean. We can maybe mention this issue as a small example.

[Copilot]

Reworked in 920da00 — the section now leads with general advice (delete artifacts, then git clean -xdf if that doesn't help) and uses the MSB3103/rename case as a concrete example.

[mwiemer-microsoft]

@copilot make the suggested changes

[Copilot]

@copilot make the suggested changes

Applied both suggestions in 920da00: consolidated the troubleshooting section into the Windows doc only (Unix doc now links to it), and generalized the guidance to lead with wiping artifacts then git clean -xdf, using MSB3103 as the example.

[Copilot]

🟡 Changes recommended

Add explicit Windows Remove-Item and Unix/macOS rm -rf cleanup commands.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Lite