What are these DISCUSSION, RECOMMENDED, CONSIDER, etc. keywords popping up?

[riverar]

I was reviewing PR #458 this evening and discovered #458 (comment) from @jonwis:

RECOMMEND: Use PushNotificationActivationInfo as the name here. Related to the unpackaged app activation APIs, which take in GUIDs or command line.

DISCUSSION: This is a way to short-circuit hooking up CoRegisterClassObject or single-instancing a second wmain launch so a running app can just listen on the event. If an app has this event connected, all notifications come here instead of going to the activation.

CONSIDER: Should there be an API on the incoming notification request that is like .Handled(true) which prevents the event from turning into an activation? That lets us retain "event handlers don't change behavior" rules. [...]

Can you provide more information on this convention?

[jonwis]

TL;DR - those tags are the result of API review and provide direction for the API author/owner on how they might change the API or its documentation.

Windows has an API design & review process for all APIs in the Windows SDK. During feature design, API authors build a specific document with samples, IDL (or headers), and commentary for developers to understand how and why to use their new feature.
A group of design representatives from across Windows comments on that design. Typically a smaller group - the representatives with direct connections to the API - meet to review the comments. We discuss the shape of the API, the relationship of the entities within it, how it relates to other coming work, using the right "name parts" for types and methods, and even its future evolutions. The output of those discussions are left as comments in the specification using keywords to distinguish them from questions left pre-review:

• RECOMMEND: "You the API owner should apply this feedback to the spec or API"
• DISCUSSION: "We chatted and the salient point was yyy, but no change is requested"
• SAMPLE: "The sample has an issue unrelated to the API being designed"
• CONSIDER: "You the API representative should strongly consider this additional information and maybe make a change."

A core value of Project Reunion is working in the open with our developer partners (that’s you!) … we’re adapting the internal review process for Windows SDK APIs to Project Reunion, following the same path as WinUI and their XAML Controls work. Unfortunately we can’t open-source the 8+ year backlog of Windows API design & review work.

During the coming weeks I'll be pushing up a few things:

• Publishing our API review process under https://github.com/microsoft/ProjectReunion/tree/main/docs
• Distilling our Windows API Design Guidelines & Patterns documents (loosely derived from the original .NET API Design Guidelines) and making them public
• Figuring out how to involve Project Reunion participants more fully in the review process

The .NET folks have been doing this for a while for their process, notes, and history. There’s also Azure's REST SDK API design guidelines. Sadly we can't put the Windows API design & review process in the open as we - naturally - discuss undisclosed future features in detail. Luckily the design guidelines we follow can be published since they contain neither of those. (Coming soon-ish!)

Historically this heavyweight review flow was required since Windows has a no-breaking-changes-once-shipped policy for both source and ABI compatibility. "Windows Runs All Your Apps, Forever." We got one shot at designing and building the APIs for the product, implying they needed to be durable for many releases and consistent across the SDK. The API Design Representatives intentionally act like external developers without knowledge of how the feature works so we can help the API see how someone outside their team would experience their feature, and that helps get the right API shapes built up front.

Project Reunion's ability to introduce both source and ABI breaking changes limits the need for looking ahead so many years and settling on a single API now and forever. This might let us go a little softer on the group-review-process, but I still require any API with a "Microsoft Windows" provenance to have gone through some form of review with those semi-impartial representatives.

I'll noodle on how to make these review events more publicly accessible, probably through additional "hey this is coming" messages and sharing a publicly-accessible Teams instance for folks to join and observe.

For now, please do leave comments on our pending API reviews. There's a handful, and we'll be reviewing more of them over the next few weeks.