search

watson-developer-cloud / homebrew-tools

DEPRECATED: this repo is no longer actively maintained
3 stars 3 forks source link

Please do not use acronyms #2

Closed germanattanasio closed 7 years ago

germanattanasio commented 7 years ago

Do not use acronyms like wdccli. It needs to go away asap.

See: https://github.com/watson-developer-cloud/api-guidelines/blob/master/repository-guidelines.md

germanattanasio commented 7 years ago

When I say "asap" it's because If we leave it there people will start adopting it and the migration will be harder.

colindean commented 7 years ago

@bruceadams All you.

bruceadams commented 7 years ago

Well, the wdscli name already exists. Admittedly, I created that name. I do not see a reasonable way to both:

  1. avoid using the wdscli name and
  2. include wdscli in this Homebrew tap

I see two possible solutions:

  1. accept the reference to the wdscli name here
  2. remove wdscli from this Homebrew tap.

I prefer keeping wdscli in here, but I see that it does fall outside the standards for this organization. Removing wdscli is an acceptable solution. @germanattanasio Which path would you prefer?

germanattanasio commented 7 years ago

Can we add another name and keep wdscli but not document it? That way it will be a backward compatible change.

bruceadams commented 7 years ago

Renaming is sounding more attractive as I think about it. One of the existing big problems with the wdscli name is how does one say it out loud? Watson Discovery Service Command Line Interface is just way too long to speak, type or even read.

So, what name to use? If we assume some context, such as IBM Watson and Command Line, the word that remains is Discovery. As a command line program, it really needs to be lowercase. So, what do you think of discovery? Looking in Homebrew and Ubuntu's (huge) package repository, I don't see anything else named discovery.

(A follow-on question is: Should we move the repo from under me, https://github.com/bruceadams to under here? But that question can be addressed separately.)

germanattanasio commented 7 years ago

watson-discovery. It aligns with our long-term naming which doesn't include developer cloud

bruceadams commented 7 years ago

watson-discovery is awfully long for something to be typed as a command.

bruceadams commented 7 years ago

I'm fine with having multiple names, where the repository is named watson-discovery, and we go for brew install watson-discovery but the command itself, as available to the user, needs to be shorter, such as discovery. I'll add a commit to my pull request making that adjustment.

colindean commented 7 years ago

I'm OK with the formula being called watson-discovery-cli or watson-discovery- tool and the executable being discovery-tool or disco or disco- cli or disco-tool.

germanattanasio commented 7 years ago

@bruceadams why are you saying that the command needs to be shorter? is there a restriction on a number of characters we use? what happens when we want to add tools for other services like Conversation. Should we use only conversation? I think the pattern should be watson-conversation, watson-discovery, watson-visual-recognition, etc...

bruceadams commented 7 years ago

Can you point at any command line tool that you actually use that has a name anywhere near as long as those examples?

I'm thinking Unix-style commands: ls, grep, awk, sed, ps, vim. More specialized command names start to get longer, but they are still short: git, emacs, find, sort.

colindean commented 7 years ago

I could see a convention kinda like git where all of the git commands are really executables such as git-pull and git-rebase. 

$ watson discovery submit file.json

just executes watson-discovery on the underside.

That's outside of the scope of this discussion, though.

germanattanasio commented 7 years ago

@bruceadams: we can discuss the benefits of using short names vs more readable or extensible names forever and I think we will always find valid arguments for both approaches. I'm trying to keep some consistency and we already have 2 CLIs using the following pattern:

We have two CLIs using the same pattern:

Let's use watson-discovery-utils.

bruceadams commented 7 years ago

Ah! I was not aware of these existing command line tools. That helps me a lot.

I remain uncomfortable with such a long name for a command. (Having a long name for the Github repository is just fine,; I'm only concerned about what the user is typing repeatedly.)

But, I am quite uncomfortable with the existing wdscli name as well. So, I'm willing to make the leap to a long name. I dislike utils. Utils strikes me as going outside the naming guidelines

We avoid abbreviations …

My counter proposal is watson-discovery-tool. I'll redo my pull request using this name.

(Side comment on our handing of this issue: My understanding of our conversation in this issue is that we have made steady progress; that we are not talking in circles nor only arguing for the sake of arguing. My previous update gave some examples to explain where I was coming from and I asked you for counter examples. You gave me solid counter examples. Even better, your examples came from within https://github.com/watson-developer-cloud/.)