{docs} docs template for extension

[msyyc]

---

This checklist is used to make sure that common guidelines for a pull request are followed.
RE: New devOps work item for autogenerating CLI release notes
https://docs.microsoft.com/en-us/cli/azure/azure-cli-extensions-list?view=azure-cli-latest

General Guidelines

• Have you run azdev style <YOUR_EXT> locally? (pip install azdev required)
• Have you run python scripts/ci/test_index.py -q locally?

For new extensions:

• My extension description/summary conforms to the Extension Summary Guidelines.

About Extension Publish

There is a pipeline to automatically build, upload and publish extension wheels.
Once your PR is merged into master branch, a new PR will be created to update src/index.json automatically.
The precondition is to put your code inside this repo and upgrade the version in the PR but do not modify src/index.json.

[yonzhan]

docs

[dbradish-microsoft]

This same response is in email thread with subject "New devOps work item for autogenerating CLI release notes".

---

From: Delora Bradish
Sent: Wednesday, April 28, 2021 11:45 AM
To: Yuchao Yan [email protected]; Shuang Jiang [email protected]; Yong Zhang [email protected]; Feng Zhou [email protected]; Jiashuo Li [email protected]
Cc: Catherine Zhu [email protected]; Yu Chen [email protected]
Subject: RE: New devOps work item for autogenerating CLI release notes

Hello, Yuchao.

Thank you for the screen print. I looked at the PR, but your screen print gave a great visual.

Questions:
 How is the “Reference” and “Extension” columns different? Since we can’t have the ‘az referenceName’, how about one column called “Extension name”?

 Extensions can also be experimental. If the “Preview” column is just for one of three status (experimental, preview, GA), where can we communicate “experimental”?

 Where is the current “Reference” column link taking the customer? Using “account” as an example…
o az account alias is an extension
o az account management-group is core
o az account subscription is an extension
This link should not be going to GitHub. We need to drive customers to our autogenerated reference content where engineering has put a lot of effort into meaningful examples.

Since our RWG (Reference Working Group) DevOps work items have not made the list for Q4, we are in a position of really needing to ramp this article up, and do the same layout for Core if possible. Can this pipeline run after the autogen reference process and use the files found in azure-docs-cli/latest/docs-ref-autogen at master · MicrosoftDocs/azure-docs-cli (github.com) as a source? I’m just grasping at straws here …

In the end, we are trying to communicate through this document, “Here is a list of Azure CLI extensions and their status. Click for detail description, parameter information, and script examples”.

Kindly,

Delora

[fengzhou-msft]

I think Minimum Version refers to the azext.minCliCoreVersion. Instead of changing the value for extension.version, changing the variable name to extension.min_cli_core_version would be more clear. And we can still put extension.version as the text for Release Notes column instead of all the same hard-coded history.

A split of Reference and Extension Name columns seems not necessary, they're bothing showing the extension name.

[fengzhou-msft]

Minimum Version is a bit ambigous, Minimum CLI Version is more clear.

[fengzhou-msft]

Suggest to change the Preview column to Status and the value can be Experimental/Preview/GA.

[msyyc]

According to the review suggestion, the UI is like:

[fengzhou-msft]

@msyyc you can combine Latest Version and Release Notes by keeping only the Release Notes column, but the text is a version like 0.2.1 and it contains a link to the history note url.

[msyyc]

@fengzhou-msft