Porting STL Visualizers to the VS repository

The STL's debug visualizers live in a single file STL.natvis. STL.natvis has three homes:

1. GitHub: stl/debugger/STL.natvis
2. MSVC: src/vctools/crt/github/stl/debugger/STL.natvis
3. VS: src/vc/debugger/CppEE/src/Visualizers/STL.natvis

The copy in the VS repo is the one that actually ships with VS. The existence of multiple copies is the result of our desire to keep the visualizers "close" to the STL types they visualize and to facilitate visualizer contributions. Changes in GitHub propagate into the MSVC repo as part of our normal mirroring process. Propagation to VS is manual. We try to propagate an updated STL.natvis when the toolset produced from MSVC which includes that updated natvis file is inserted into the VS repo, but don't always manage to do so in a timely manner.

The VS update process is more complicated than the simple mirror we do between GitHub and MSVC. With enlistments available for VS and MSVC or STL:

1. Copy the MSVC / STL STL.natvis over the copy in your VS enlistment, and verify that the changes are as expected with git diff.
2. Create a VS branch - I like dev/cacarter/natvis - and prepare a commit message. Ideally the commit message will list the GitHub PRs that contributed the changes to STL.natvis. See VS-PR-582133 for an example.
3. Push your branch and open a draft PR for VS. Queue the build ("CloudBuild - PR") and "Request GlassTests (Debugger)".
4. The pipelines will add comments to the PR. When the Glass tests complete, the corresponding comment will be updated with information on failed tests (click to expand "Failed details").
   • The Glass tests tend to be pretty flaky in general, so much so that the comments are annotated to indicate tests that are considered flaky or broken. Not every failure you see will be a consequence of your changes.
   • The Glass tests each run a program (the "debuggee") inside the debugger. There is a script of input events Glass sends to and output events it expects from the debugger. Where there are __debugbreak calls in the debuggee, Glass dumps the debugger state and compares it with a baseline.
   • When we update STL.natvis we need to update the baseline for related tests, or even unrelated tests when baselines contain STL.natvis line numbers.
   • The native debuggees and their baselines all live under src/vc/debugger/CppEE/tests/NativeEE in the VS repo.
5. For each failing test you need to examine the attachments.
   • The presence of vsassert.txt generally indicates Very Bad Things™ caused the test to crash. To my knowledge this always indicates either a bug in the debugger or Glass, or a transient test failure of some kind; ignore or rerun.
   • Otherwise, the attached Errors.log should contain a diff of the pertinent baseline file (EETestN.baseline.xml or EETestN.baseline.x64.xml) with the attached observed result.
   • If the diff is consistent with your expectations from the STL.natvis changes, replace the baseline in your branch with the attached observed result.
   • If the diff isn't consistent with your expectations, things get more complicated quickly. An unexpected event indicates a problem with the debugger or debuggee. Reach out to the CppEE owner on @<VS Debugger> (@<Xinyu Sui> as of this writing) for help or ask @<Casey Carter>.
6. Once you've reviewed the failures and locally committed baseline changes, push the update to your PR and "Publish" it in Azure DevOps. Make sure the required pipelines and the Glass tests are all queued. Add @<VC Libraries> and the CppEE maintainer as optional reviewers.
7. Get approvers to check off so you can merge the PR. Promise them candy.
8. If you've ported new visualizers or significant updates, add a Changelog entry indicating when they will ship.