[Se] Implementation of TypeSpec 'infoblurb' Mechanism in Brownfield PRs

[mario-guerra]

API Spec link

NA

API Spec version

NA

Please describe the feature.

We need to set up a mechanism to insert a non-blocking, high-visibility comment in every brownfield PR for services not yet converted to TypeSpec. This is part of the Brownfields adoption plan, aiming to encourage early adoption of TypeSpec conversion. The comment should inform teams about the TypeSpec tool and offer hands-on assistance from the TypeSpec Onboarding Support team for early adopters. It's crucial that this comment does not block PR merging and can be suppressed by teams blocked from converting due to pending centralized work.

Criteria for the comment to appear:

• The PR is for handwritten swagger.
• No suppression for TypeSpec conversion has been applied.

Action:

• Add a non-blocking comment to the PR with predefined text encouraging early TypeSpec conversion and offering support.

This setup should not include any blocking warnings, only a non-blocking comment. The text of the comment should be as follows:

NOTE - Brownfield services will soon be required to convert from OpenAPI to TypeSpec. The TypeSpec team has developed a tool to assist with this transition. By converting early, you’ll receive hands-on assistance and provide valuable feedback to improve the tool. Contact TypeSpec Onboarding Support to join a select group of early adopters and ensure a smooth transition.

[mikeharder]

I think this should be added to the existing check "TypeSpec Requirement", which already has the logic to determine greenfield vs brownfield. Here's the conclusion of the check:

azure-rest-api-specs/eng/scripts/TypeSpec-Requirement.ps1

Lines 169 to 175 in 46b3863

	if ($responseStatus -eq 200) {
	LogInfo " Branch 'main' contains path '$servicePath/stable', so spec already exists and is not required to use TypeSpec"
	}
	elseif ($responseStatus -eq 404) {
	LogInfo " Branch 'main' does not contain path '$servicePath/stable', so spec is new and must use TypeSpec"
	$pathsWithErrors += $file
	}

After L170, the check should additionally:

• Print a notice (pointing to the spec file)
  • This should appear in the check summary and the "code review" tab, giving two places for spec authors to see it.
• Add a label brownfield
  • The label description should be a short URL pointing to TSP conversion instructions
  • Can be used for querying open PRs
  • Will also be used by the "Next Steps to Merge" (NSTM) comment generator to include the blurb

And last but not least:

• Update NSTM to include the blurb

[mikeharder]

@mario-guerra, @MattGertz: What should happen if check TypeSpecRequirement is suppressed? Should it be skipped or still apply? The initial feature request says "skip", but I wanted to double-check.

Currently, the tool checks for suppressions very early, and skips all other analysis if the check is suppressed. Since we want very much to avoid the tool failing or crashing if the spec author has suppressed it.

azure-rest-api-specs/eng/scripts/TypeSpec-Requirement.ps1

Lines 83 to 90 in b88e6ad

	$suppression = Get-ValidatedSuppression $fullPath
	if ($suppression) {
	$reason = $suppression["reason"] ?? "<no reason specified>"
	LogInfo " Suppressed: $reason"
	# Skip further checks, to avoid potential errors on files already suppressed
	continue
	}

So if TSR is suppressed, it will also suppress all the brownfield notices. Currently, I believe very few specs should have TSR suppressed, and any which do should be tracked by ARM or DP.

[mario-guerra]

@mikeharder it's fine if the infoblurb is suppressed when the TSR suppression is applied.

[mikeharder]

Mostly completed in #31814. Remaining work:

• Review and update notice text
• Mirror to azure-rest-api-specs-pr and update required checks
• Add notice to "Next Steps to Merge" comment, based on presence of label "brownfield"
• Add lessons learned to "GitHub Action Best Practics" wiki page

[mikeharder]

@mario-guerra, @MattGertz: This work item should be mostly complete. First, please review the text I'm currently using for the notice, which is shorter than what was suggested originally:

Brownfield services will soon be required to convert from OpenAPI to TypeSpec. See https://aka.ms/azsdk/typespec.

I'd like to keep the message itself relatively short so it doesn't get cutoff in the GitHub UI, with a link to more details (that's also easier to update than the check itself). But I can test a longer message and see how it looks.

Second, if possible, I'd like to defer adding the notice to the "Next Steps to Merge" comment until this component is moved to our new engineering system, so we don't need to make this change in our old system. But, I can add it to the old system, if we think the current implementation of the notice isn't visible enough.

For tracking purposes, I will close this issue, and we can open new issues or PRs for future work.