add bcd link for cli upgrade #3768
Conversation
|
Learn Build status updates of commit f56ba74: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
|
|
|
Learn Build status updates of commit 20c5caf:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| docs-ref-conceptual/update-azure-cli.md | View | Details | |
| docs-ref-conceptual/media/azure-cli-diff-site.gif | ✅Succeeded | ||
| docs-ref-conceptual/media/command-change.gif | ✅Succeeded |
docs-ref-conceptual/update-azure-cli.md
- Line 61, Column 1: [Warning: alt-text-bad-value - See documentation]
Alt text 'command-change' is the same as the image file name. This redundancy adds no value for users of screen readers. For accessibility, add more descriptive alt text. - Line 61, Column 1: [Warning: link-out-of-scope]
File 'docs-ref-conceptual/media/command-change.gif' referenced by link 'media/command-change.gif' will not be built because it is not included in build scope. - Line 65, Column 1: [Warning: alt-text-bad-value - See documentation]
Alt text 'azure-cli-diff-site' is the same as the image file name. This redundancy adds no value for users of screen readers. For accessibility, add more descriptive alt text. - Line 65, Column 1: [Warning: link-out-of-scope]
File 'docs-ref-conceptual/media/azure-cli-diff-site.gif' referenced by link 'media/azure-cli-diff-site.gif' will not be built because it is not included in build scope.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
| ## Update Assistance | ||
|
|
||
| Azure cli also provides a command line tool [command-change](https://github.com/Azure/azure-cli-extensions/blob/main/src/command-change/README.md) and a [azure-cli-diff-site](https://azure-cli-diff-site.azurewebsites.net/) to help users justify whether a cli upgrade is safe, how to adjust current command usage by checking the changelist between two cli versions. For detailed usage doc and result analysis, please refer to this [doc](https://github.com/Azure/azure-cli/blob/897a4cd2874e315558d1f1925e866a80ab945f18/doc/breaking_change_detection_guidelines.md). |
There was a problem hiding this comment.
Suggestion 1: [command-change](https://github.com/Azure/azure-cli-extensions/blob/main/src/command-change/README.md)
We should not be sending customers to GitHub from conceptual content unless it is for a sample. Can this be changed to a link to our autogenerated reference content?
Comment 2: I'm thinking about SEO. Can the azure-cli-diff-site.azurewebsites.net be given a H1 name? The only way for our customers to find this URL is through this one conceptual doc link?
Suggestion 3: This information is very informative and I feel needs to be in azure-docs-cli published in the same node as our Breaking Changes doc --> [doc] (https://github.com/Azure/azure-cli/blob/897a4cd2874e315558d1f1925e866a80ab945f18/doc/breaking_change_detection_guidelines.md)
Suggestion 4: Can we reword this paragraph to something along the lines of ...
"The Azure CLI also provides a reference command, [az command-change](link to ref content), and a website, azure-cli-diff-site, to help you examine changes between CLI versions. Use the version comparison list provided to prepare your scripts for a version update. See [Breaking change detection for the Azure CLI](link to new doc in azure-docs-cli) for more information.
There was a problem hiding this comment.
@dbradish-microsoft, thanks for the good suggestions.
- Agree we put the content in https://github.com/Azure/azure-cli/blob/897a4cd2874e315558d1f1925e866a80ab945f18/doc/breaking_change_detection_guidelines.md) to azure-docs-cli and both "Update" and "Upcoming Breaking Changes" nodes can reference that doc.
- GitHub repo can have link from learn site as https://review.learn.microsoft.com/en-us/cli/azure/use-cli-effectively?branch=pr-en-us-3768&tabs=bash%2Cbash2 does does.
- Regarding SEO, not sure if it's necessary as I don't think customers will get the site via search engine. But we may provide an official site name
azurewebsites.netis more like an internal site name.
@dcaro, @Jacekey23 how about your thoughts?
There was a problem hiding this comment.
I think this is misleading in the upcoming breaking change since the tools does not show content of future versions.
SEO is important, search is the primary way people discover content nowdays.
|
Learn Build status updates of commit 977cde3:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| docs-ref-conceptual/update-azure-cli.md | View | Details | |
| docs-ref-conceptual/media/azure-cli-diff-site.gif | ✅Succeeded | ||
| docs-ref-conceptual/media/command-change.gif | ✅Succeeded |
docs-ref-conceptual/update-azure-cli.md
- Line 61, Column 1: [Warning: link-out-of-scope]
File 'docs-ref-conceptual/media/command-change.gif' referenced by link 'media/command-change.gif' will not be built because it is not included in build scope. - Line 65, Column 1: [Warning: link-out-of-scope]
File 'docs-ref-conceptual/media/azure-cli-diff-site.gif' referenced by link 'media/azure-cli-diff-site.gif' will not be built because it is not included in build scope.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
| ## Update Assistance | ||
|
|
||
| The Azure cli also provides a reference command, [az command-change](https://github.com/Azure/azure-cli-extensions/tree/main/src/command-change) and a website, [azure-cli-diff-site](https://azure-cli-diff-site.azurewebsites.net/), to help you examine changes between CLI versions. Use the version comparison list provided to prepare your scripts for a version update. See [Breaking change detection for the Azure CLI](https://github.com/Azure/azure-cli/blob/dev/doc/breaking_change_detection_guidelines.md) for more information. |
There was a problem hiding this comment.
The links provided here should point to the conceptual and reference documentation associated with the command.
| ### command-change | ||
| Here is example output for [az command-change](https://github.com/Azure/azure-cli-extensions/tree/main/src/command-change): | ||
|  |
There was a problem hiding this comment.
The animated gif is a challenge in terms of accessibility and does not add much value. Please consider converting this to static text.
| ## Update Assistance | ||
|
|
||
| Azure cli also provides a command line tool [command-change](https://github.com/Azure/azure-cli-extensions/blob/main/src/command-change/README.md) and a [azure-cli-diff-site](https://azure-cli-diff-site.azurewebsites.net/) to help users justify whether a cli upgrade is safe, how to adjust current command usage by checking the changelist between two cli versions. For detailed usage doc and result analysis, please refer to this [doc](https://github.com/Azure/azure-cli/blob/897a4cd2874e315558d1f1925e866a80ab945f18/doc/breaking_change_detection_guidelines.md). |
There was a problem hiding this comment.
I think this is misleading in the upcoming breaking change since the tools does not show content of future versions.
SEO is important, search is the primary way people discover content nowdays.
Co-authored-by: Damien Caro <[email protected]>
|
Learn Build status updates of commit e3892de:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| docs-ref-conceptual/update-azure-cli.md | View | Details | |
| docs-ref-conceptual/media/azure-cli-diff-site.gif | ✅Succeeded | ||
| docs-ref-conceptual/media/command-change.gif | ✅Succeeded |
docs-ref-conceptual/update-azure-cli.md
- Line 60, Column 1: [Warning: link-out-of-scope - See documentation]
File 'docs-ref-conceptual/media/command-change.gif' referenced by link 'media/command-change.gif' will not be built because it is not included in build scope. - Line 64, Column 1: [Warning: link-out-of-scope - See documentation]
File 'docs-ref-conceptual/media/azure-cli-diff-site.gif' referenced by link 'media/azure-cli-diff-site.gif' will not be built because it is not included in build scope.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
No description provided.