search

Azure / azure-sdk-for-js

This repository is for active development of the Azure SDK for JavaScript (NodeJS & Browser). For consumers of the SDK we recommend visiting our public developer docs at https://docs.microsoft.com/javascript/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-js.
MIT License
2.07k stars 1.19k forks source link

Readme Content Verification - need to format readmes to match template doc #1583

Closed scbedd closed 3 years ago

scbedd commented 5 years ago

The following data-plane items need to be addressed. Validation has failed on the following readme list items.

tl;dr: Readmes should have at least have sections that correspond to the main sections as defined in the template readme.

This is what the tool checks, but the ideal scenario is the readme is reworked to be somewhat like the readme example.

For a rundown on what you need to do to resolve these breaking issues ASAP, check out aka.ms/azure-sdk-analyze-failed

ITEMS

47 readmes have at least one missing required section.

(the others below have the exact same missing sections)

jeremymeng commented 5 years ago

It looks like not every README.md in the repo needs to follow the main README structure. Cosmos DB has the following files

scbedd commented 5 years ago

@jeremymeng I think I'd agree with you for everything under src and samples. The main readme definitely should though.

Add the following members to the omitted_paths list

  - sdk/cosmosdb/cosmos/src/test/*
  - sdk/cosmosdb/cosmos/samples/*

There is deliberately NO justification here. We just never expect them to match. This isn't an "exception" anymore.

For the main readme (sdk/cosmosdb/cosmos/README.md) I do feel that this should align. You did the correct thing by putting it with an exception.

I've edited the master issue list to include only the main readme in the list.

jeremymeng commented 5 years ago

@scbedd Yes, the main readme will be fixed and #2248 tracks that work.

sophiajt commented 5 years ago

Do we have a list of outstanding files that don't confirm as part of this issue?

KarishmaGhiya commented 3 years ago

The readme verification script that is being used for verification of readme content for all packages should update it's logic to only include the packages readme and only for track 2 packages and only the readmes at the path : sdk\service\package\readme Currently it shows up issues for all the readmes in the repo like the samples readme.md and the swagger readme.md - these readmes will never align with the guidelines. Logged issue to track this https://github.com/Azure/azure-sdk-tools/issues/1530

KarishmaGhiya commented 3 years ago

Will be opening issues for track 2 packages that don't align with the readme guidelines.

Regenerate the list of packages that don't follow the verification and assign issues to the service sdk's package owners (with specific sections) : ○ If the service sdk is in preview - make sure readme is fixed before GA ○ Other services which are already GA, make sure readme is updated in next patch release ○ Encourage them to make other languages follow the same structure If a lot of sdks feel some headers don't make sense at all - we'll circle back with the EngSys team

deyaaeldeen commented 3 years ago

@KarishmaGhiya

these readmes will never align with the guidelines.

Long-term, https://github.com/Azure/autorest.typescript/pull/895 addresses this issue by including the required sections in the auto-generated readmes. So once all packages adopt the new code gen, all readmes will follow our guidelines. You can still of course still choose to not verify those readmes, at least for the time being. cc @ramya-rao-a

KarishmaGhiya commented 3 years ago

@deyaaeldeen Yes we can use that issue for the track 1 packages readme that are autogenerated. Will that also make the readme generated by swagger similar to package readme? This is an example of the swagger readme I am refering to - https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/metricsadvisor/ai-metrics-advisor/swagger This is an example of the samples readme I am refering to - https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/metricsadvisor/ai-metrics-advisor/samples/javascript/README.md These readmes will be different from the package readmes.

deyaaeldeen commented 3 years ago

@KarishmaGhiya you're right, the swagger and samples readmes will never follow the package readme structure and have to be excluded from validation.