Cadl repo structure guidelines

[tjprescott]

Closes https://github.com/Azure/cadl-azure/issues/1691.

Relocated from original PR: https://github.com/Azure/cadl-azure/pull/2021

[openapi-pipeline-app[bot]]

Swagger Validation Report

️️✔️BreakingChange succeeded [Detail] [Expand]

There are no breaking changes.

️️✔️Breaking Change(Cross-Version) succeeded [Detail] [Expand]

There are no breaking changes.

️️✔️CredScan succeeded [Detail] [Expand]

There is no credential detected.

️️✔️LintDiff succeeded [Detail] [Expand]

Validation passes for LintDiff.

️❌Avocado: 1 Errors, 0 Warnings failed [Detail]

Rule	Message
❌ MISSING_README	Can not find readme.md in the folder. If no readme.md file, it will block SDK generation. folder: _work/1/c93b354fd9c14905bb574a8834c4d69b/documentation

️️✔️ApiReadinessCheck succeeded [Detail] [Expand]

️️✔️~[Staging] ServiceAPIReadinessTest succeeded [Detail] [Expand]

Validation passes for ServiceAPIReadinessTest.

️️✔️ModelValidation succeeded [Detail] [Expand]

Validation passes for ModelValidation.

️️✔️SemanticValidation succeeded [Detail] [Expand]

Validation passes for SemanticValidation.

️️✔️PoliCheck succeeded [Detail] [Expand]

Validation passed for PoliCheck.

️️✔️PrettierCheck succeeded [Detail] [Expand]

Validation passes for PrettierCheck.

️️✔️SpellCheck succeeded [Detail] [Expand]

Validation passes for SpellCheck.

️️✔️Lint(RPaaS) succeeded [Detail] [Expand]

Validation passes for Lint(RPaaS).

️️✔️CadlValidation succeeded [Detail] [Expand]

Validation passes for CadlValidation.

️️✔️PR Summary succeeded [Detail] [Expand]

Validation passes for Summary.

_{Posted by Swagger Pipeline | How to fix these errors?}

[openapi-pipeline-app[bot]]

Swagger pipeline restarted successfully, please wait for status update in this comment.

[openapi-pipeline-app[bot]]

Swagger pipeline restarted successfully. If there is ApiView generated, it will be updated in this comment.

[heaths]

1. FWIW, this is an exact duplicate at the time of this writing with the guidelines from the old PR.
2. Were you going to transfer over the versioning spec?
3. Do you have plans to copy over comments on the PR, or will you address them there first? There were quite a few open comments.

[tjprescott]

@heaths no this has been updated based on our working group meeting from earlier this week. Versioning was split out because we didn't discuss it, so that is still an open question.

[weshaggard]

Lets please get https://github.com/Azure/azure-rest-api-specs/blob/main/README.md#directory-structure updated and linked to this new document as well.

[weshaggard]

@tjprescott can you pull in the versioning information back into this document now and also update the contributing md file to point to this new document? Let me know if I can help move this forward so we can get this PR merged in.

[tjprescott]

Most of the docs look good to me but I'd like to see the cadl stuff at https://github.com/Azure/azure-rest-api-specs/blob/main/README.md#directory-structure updated before merging this.

@weshaggard I've updated both README.md and contributing.md

[openapi-workflow-bot[bot]]

Hi @tjprescott, Your PR has some issues. Please fix the CI sequentially by following the order of Avocado, semantic validation, model validation, breaking change, lintDiff. If you have any questions, please post your questions in this channel https://aka.ms/swaggersupport.

Task	How to fix	Priority
Avocado	Fix-Avocado	High
Semantic validation	Fix-SemanticValidation-Error	High
Model validation	Fix-ModelValidation-Error	High
LintDiff	Fix-LintDiff	high

If you need further help, please feedback via swagger feedback.