Disclaimer: Don't take the tone of this issue too seriously, it's just a representation of a user's frustration, not necessarily mine π Read this as a story.
Alright! AsyncAPI has a CLI, this is cool. I'm gonna install it and validate my file.
npm install -g @asyncapi/cli
Lovely. Let's now validate my AsyncAPI file:
$ asyncapi validate
No contexts saved yet, run asyncapi --help to know more.
Oh! My fault, I have to provide the file name:
$ asyncapi validate asyncapi.yml
No contexts saved yet, run asyncapi --help to know more.
β π
context? what the f*ck is a context? what do they mean by context? ok, let me try with asyncapi --help
:
(redacted)
context
current show the current set context
list show the list of all stored context
remove <context-name> remove a context from the store
use <context-name> set any context as current
add <context-name> <filepath> add/update new context
Examples
$ asyncapi context add dummy ./asyncapi.yml
$ asyncapi validate --context=dummy
$ asyncapi validate --file=./asyncapi.yml
π€¦ Ok, now I know I can create contexts, list contexts, remove contexts, and obviously add them. But I still don't know what is a "context".
HOW DO I VALIDATE MY FILE FOR GOD SAKE!?
Oh, wait, from the examples I can guess I need to add my file to a "context" and then run asyncapi validate --context=my-context
. Let's do that.
Cool! How do I name my context? Let me think about it well so I don't create a stupid context name for later. Or maybe I can just use "test" for now. I wonder where this information is stored π€
Anyway, let's just use "test"
asyncapi context add test ./asyncapi.yml
asyncapi validate
Cool, it works now. Oh wait, there was a shorter way! π€¦ I could just have done:
asyncapi validate --file=./asyncapi.yml
Do you see where I'm going? I agree contexts can be useful for experienced and regular users but for newcomers, having to deal with the burden of contexts for simple things like validating a file is such a huge barrier that shouldn't exist.
My proposal is that we remove contexts completely. I think they may make sense in the future βwho knows?β but for now, this is only making things more difficult to reason about. Instead, we can rely on a convention over and then configuration style. For instance:
Would look for files with the name asyncapi.yml
, asyncapi.yaml
, or asyncapi.json
in the current directory. If it's found, it validates the file. If it's not, it fails and shows a message saying it couldn't find an asyncapi file and suggesting how to continue.
Following what we discussed on #1, I think asyncapi verb noun
should be respected. The noun
may be optional when we can easily default to something. Like this case or the case of asyncapi new
which could be the equivalent of asyncapi new file
. I'm always in favor of options/flags over arguments but if an option is mandatory, it's not an option.
But Fran, my file is called something else, like spec.yml and I still want to benefit from short commands
Cool, now we introduce contexts. The user is going to enable the "contexts" feature knowing what they're doing and on purpose.
$ asyncapi enable contexts
Awesome! From now on, I'll use the `default` context.
Please add your AsyncAPI file to the context:
asyncapi update context your-asyncapi-file.yml
$ asyncapi update context spec.yml
β
Your AsyncAPI file (spec.yml) has been added to the `default` context.
Note I keep using the pattern asyncapi verb noun
and I'm always trying to go ahead of the user. For instance, I decided there's going to be a default
context (eliminating the need to think about a name). Users should be able to customize the name if they prefer, doing asyncapi enable contexts --context=my-context-name
. With asyncapi update context your-asyncapi-file.yml
, we could even go further and make the file name optional, and if you run asyncapi update context
the CLI will prompt you a file name or fail if stdin is not interactive.
Summary
In short, I think we should be making the UX seamless for newcomers and let experienced and avid users to get the most out of the CLI by letting them configure the behavior. Let's assume defaults and conventions whenever possible. Let's make them configurable via options/flags or interactive terminal when possible.