Always follow the same structure (verb + noun, noun + verb, or namespace + verb + noun)

[fmvilas]

I think we should be following a structure, regardless of the command at hand. For instance:

asyncapi validate file

Is following the verb + noun approach. Whereas:

asyncapi context add

Is reversing it to noun + verb.

In #1, I suggested we use verb + noun because it reads naturally. However, after thinking about how to flip contexts and how to occasionally evolve them to accept multiple asyncapi files, it seems the noun + verb might work better here. Just like the Github CLI. So for instance, if I want to add one more asyncapi file to a context, how would it be?

asyncapi add context # that sounds like adding a context not "adding to" a context
asyncapi add-to context # clear but ugly

So maybe it's a better idea to go for something like:

asyncapi context add # Creates a context
asyncapi context add file # Adds a file to a context

In this case, the structure would be something like noun + verb + [noun] (being the last noun optional). To avoid confusion, I suggest we call it namespace + verb + [noun] because the first noun actually works like a namespace.

[derberg]

I suggested asyncapi context add and others as it feels very natural when I use the same approach with GitHub CLI. I just think the verbs might be very different per noun, so verb + noun would be very strange here.

the problem is that sometimes there is just no noun, like validate or generate, so general rule sound like noun? + verb

[fmvilas]

Yeah, that's true. Maybe we should still consider the namespace and make it something like [namespace] + verb + [noun]? Just throwing ideas.

[derberg]

I have to say I'm not fully getting the namespace idea. What would it be?

[fmvilas]

Like in this case:

asyncapi context add file

It's different than:

asyncapi context add

The first one adds an AsyncAPI file to the context, the second one adds a context. The first one is, for instance, if we want to have tools like https://github.com/asyncapi/app-relations-discovery in the CLI. In that case, you don't want to manually specify all the files because they could potentially be hundreds. Does it make sense?

[derberg]

I case kubectl or github cli, stuff similar to context, go under config verb actually so it is either kubectl config get-context or gh config set editor vim. I think we should follow, as in our case context is pure config related, having it on the "root" may confuse it has anything to do with the AsyncAPI-related functionalities

We need asyncapi + verb no matter of above 😄 as context would go under config, config can be verb or noun 😄 we win as validate is verb 🤷🏼

[fmvilas]

So what would be an example? Something like:

# To add a context
asyncapi config context add

# To add a file to a context
asyncapi config context add file

Is it what you mean?

[derberg]

would be asyncapi config context add {CONTEXT_NAME} {FILE_PATH}, now it is asyncapi context add {CONTEXT_NAME} {FILE_PATH}. To follow asyncapi + verb in case of app-replations-finder aka cupid we would need asyncapi find-relations or something similar, asyncapi relate?

[Souvikns]

Just as @fmvilas said context is not a verb so asyncapi context add is breaking the (verb + noun) rule and everything else is following it. Could we name the context commands something like this

asyncapi add-context <context-name> <path>
asynapi list-context 
asyncapi use-context  <context-name>

It kind of follows the (verb + noun ) rule. What do you think ? @fmvilas @derberg

[derberg]

@Souvikns I proposed asyncapi config context add instead of asyncapi add-context as I'm simply afraid of those hyphened commands 😄 It is like this with kubectl probably also to satisfy some main rule, but not very intuitive. This is why I'm more into having config verb there. Config will not only be for context. For future, where we add more functionality, like asyncapi edit channel mychannel and open and editor like nano or vim, we will need some stuff under config to configure these editors

[Souvikns]

Will open a PR for this just to summarize the task,

• Will be removing the file flag option and adding support for input, though context will be passed through the --context flag.
• Will be moving the context command in the config namespace.

[derberg]

please split it into 2 PRs, one for moving context into config. Then another one about removing file and context flag, as I thought we agreed that technically we can remove the context flag too, right?

[derberg]

so, we have an agreement here, right?

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[fmvilas]

so, we have an agreement here, right?

I'd say so. We probably have to document it somewhere in the repo. WDYT?

[derberg]

I think what we have here is enough -> https://github.com/asyncapi/cli#command-structure-and-patterns