search

Azure / azure-cli

Azure Command-Line Interface
MIT License
4.03k stars 3.01k forks source link

What does "show" mean? #11047

Open softwarecraft opened 5 years ago

softwarecraft commented 5 years ago

Under Add cmd it says "Add a new banner and immediately show it." which indicates that "show" means "make this banner definition the active one".

Under Show cmd it says "Show details for a banner." which could mean "display the properties for one specific banner definition, whether or not it is active".

Or it could mean "make this specific banner definition the active one".

I tried to use Show cmd to change the active banner back to a prior banner definition (which is shown by the List cmd)

but this didn't work.

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

mmyyrroonn commented 5 years ago

@softwarecraft Hello. Currently, we're not own this command. Could you open an issue in https://github.com/Azure/azure-devops-cli-extension

softwarecraft commented 5 years ago

Per your direction I created https://github.com/Azure/azure-cli-extensions/issues/1056.

yonzhan commented 5 years ago

@softwarecraft https://github.com/Azure/azure-devops-cli-extension this repo, not azure-cli-extensions, correct?

softwarecraft commented 5 years ago

I am reporting an issue with the MS doc page and used the Feedback button at the bottom.

softwarecraft commented 5 years ago

There are two URLs that show the same MS doc content:

I am not going directly to GitHub to report the issue. I am using the doc page as the questions are about the accuracy of the docs.

mmyyrroonn commented 5 years ago

@yonzhan https://github.com/Azure/azure-devops-cli-extension this is an azure-cli-extension. But the source code is not owned by us. Devops team create a separate repo for their own CLI extension.

mmyyrroonn commented 5 years ago

@softwarecraft Hello. We don't have a DevOps label for now. I don't know whether they can see this issue or not. Could you please open an issue in here https://github.com/Azure/azure-devops-cli-extension?

mmyyrroonn commented 5 years ago

@softwarecraft Oh. Looks like we have a label in our extension repo. Thanks. No need to open a new issue.

yonzhan commented 5 years ago

@MyronFanQiu can we close this one?

softwarecraft commented 5 years ago

Please don't close this issue as it is not a code bug AFAIK, rather there is a need to make the docs clearer. The code repo you linked to does not contain the documentation for this extension. The docs page Feedback section links to this repo.

softwarecraft commented 5 years ago

I think the label you are looking for is "extension/devops", as you applied that to another doc issue that I reported for this same extension, https://github.com/Azure/azure-cli-extensions/issues/1057.

yonzhan commented 5 years ago

After you reported in https://github.com/Azure/azure-cli-extensions/issues/1057, do we still need this issue in azure-cli ? Since duplication.

softwarecraft commented 5 years ago

Please you decide, I'm completely confused about where to report documentation issues. I simply use the Feedback section on the doc page. It seems the doc content is duplicated under two URLs.

mmyyrroonn commented 5 years ago

@softwarecraft Hello. I'm fine to leave this issue open. To be honest, the quickest way to get the answer is to open an issue in https://github.com/Azure/azure-devops-cli-extension. We are not the owner of this extension. This line is the source of the help information. https://github.com/Azure/azure-devops-cli-extension/blob/fc1d5cd32f76a86130818afeea1ab113656d55f1/azure-devops/azext_devops/dev/admin/banner.py#L31. I checked the commands roughly, I was also confused about the meaning of the show. At least I can tell that az devops admin banner show is not the command you're looking for.

geverghe commented 5 years ago

Apologies for the delay in revert!

@softwarecraft - Including clarifications for your queries

Under Add cmd it says "Add a new banner and immediately show it." which indicates that "show" means "make this banner definition the active one".

Could you give me some more information on why you feel there is an "active" state associated with the banner? If a banner is created, the "active" period is controlled by the expiration date. There is no other explicit state set. Are you getting thrown off by the command verb "show" and attributing the show verb to actually showing/rendering the banner? If this is the issue, then maybe we need to change the command verb. Azure CLI usually uses 5 constant verbs corresponding to CRUD operations create update delete list show

Here show is adhering to the Azure CLI command paradigm of providing the ability to view the details of a particular element, and in this case a banner. This is not the verb controlling the render of the banner in the organization.

Under Show cmd it says "Show details for a banner." which could mean "display the properties for one specific banner definition, whether or not it is active".

Or it could mean "make this specific banner definition the active one".

The context on why you feel there is an explicit "active" property would help understand where we are misguiding users. The banner details as you pointed out rightly shows the properties associated with banner. Further, there is no "active" property. The render control is based on the expiration date.

I tried to use Show cmd to change the active banner back to a prior banner definition (which is shown by the List cmd)

az devops admin banner show --id '' --org https://dev.azure.com/MyOrg/ but this didn't work.

As the show command help text explain, it's only function is to show you the details of a selected banner. It has no connotations of rolling back or controlling render state.

Would it help if we include a link to our documentation - https://docs.microsoft.com/en-us/azure/devops/organizations/settings/manage-banners?view=azure-devops as part of the command help? Would it solve the above queries?

@MyronFanQiu

I checked the commands roughly, I was also confused about the meaning of the show. At least I can tell that az devops admin banner show is not the command you're looking for.

Could you help me understand where the meaning was not clear? Would examples help?

softwarecraft commented 4 years ago

Thank you for taking the time to reply in detail.

Please ignore my usage of the word "active" and replace that with "displayed".

I find the banner cmds confusing because having a collection with List and Update cmds gives me the idea that I can control which of them is displayed at any given time but this is not the case. Only the most recent added banner is displayed.

For example, what happens if I try to remove the displayed banner. Does one of the prior banners display? Or is there no displayed banner yet still a collection of banners that I can list?

What happens if I update a prior banner making its expiry date late than that of the currently displayed banner? Is that an error? Does that change which banner is displayed?

What happens with this sequence of cmds?

What if any banner is now displayed?

I have many more questions like this.

The problem is not the documentation. The problem is the design of the interface.

Simplest solution is to get rid of the collection of prior banners and the List cmd. Just keep the Add, Show, Update and Remove cmds.

If you insist on retaining the collection of prior banners, then provide clear instructions for how to update a prior banner to make it display.

Thank you