Develop semantic model of specs repo dir structure

[konrad-jamrozik]

There has been ongoing work for reviewing, updating and codifying the set of rules on what spec directory structure is allowed to be going forward. Current status is captured here:

• https://aka.ms/azsdk/spec-dirs

This work item is about:

• Aiding the process of determining the allowed directory structure by gathering relevant data.
• Leveraging that work in form of a reusable software component for all the spec PR validation tools.

Note: azure-sdk issues labelled with specs-model should be addressed by this work.

Inputs:

• The actual spec dirs in relevant branches, e.g. public main
• https://aka.ms/azsdk/spec-dirs
• Update directory-structure.md: clarify service, service group, uniform versioning. azure-rest-api-specs#28929
• Rules captured inside https://github.com/Azure/avocado
• Assumptions in openapi-alps
• To reuse as code template: [suppressions.yaml] Create shared component "get-suppressions" azure-rest-api-specs#28927
• My chat with Wes and Mike on Teams.
• Wes' source for Specification Index: https://github.com/Azure/azure-sdk/blob/main/eng/scripts/Update-Spec-Versions.ps1
• Mike K's script. See here.
• Mario's scripts powering https://aka.ms/azsdk/typespec/adoption-by-az

Output:

• Implementation of rules captured in https://aka.ms/azsdk/spec-dirs, with analysis of existing directories:
  • which directory is for service vs service group
  • details of all the services
  • which directory is violating the rules, how long it has been doing it (is it relatively new or legacy/brownfield?) and how exactly it is violating the rules (to determine if the rules perhaps require adjustment)

[mikeharder]

@konrad-jamrozik: Related?

• Enforce unified API versions in RP specs azure-rest-api-specs#28466

[konrad-jamrozik]

@konrad-jamrozik: Related?

• Enforce unified API versions in RP specs azure-rest-api-specs#28466

Yes :) Thanks!

[konrad-jamrozik]

@mikeharder can you let me know if this looks like a good way to start working on this? Any tips & tricks appreciated :)

My approach to breaking the ground on this work:

Setup

• Use suppressions as inspiration. copy-paste-adapt.
• Refer to the guide I wrote for Armstrong to understand how everything is wired together.

Milestone 1: stub implementation

1. Start with stub implementation that will at first have the "semantic model" component/tool that will do almost nothing, except printing something out. Ensure there is some basic test for it and a way to invoke it. Basically like hollowed-out empty shell of suppressions tool.
2. Then add a shell of a GitHub action, based of typespec-requirement.yaml, that will call into the shell of the semantic model component.
3. Run the pipeline and observe it calling the component and observe it printing out to the GH action run log.
4. Add GH action for tests to the semantic model component, akin to suppressions-test.yaml.
5. Do the same for typespec-requirement-test.yaml.
6. Confirm everything works:
   • The GH action workflow for the check runs and prints out expected strings from the semantic model component.
   • The GH action for the check tests runs and the stub tests pass.
   • The GH action for the semantic model component tests runs and the stub tests pass.

Milestone 2: the business logic proper

Once the shells are ready and working as explained in Milestone 1, I will start gradually adding tests specifying the desired behavior, and implementing them. This will happen over a series of PRs.