document SPIN_EXPERIMENTAL

[bacongobbler]

There are a number of CLI commands hidden to the user.

Normal output:

><> spin k8s help
Manage apps running on Kubernetes

Usage:
  k8s [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  scaffold    scaffold SpinApp manifest
  version     Display version information

Flags:
  -h, --help                help for k8s
      --kubeconfig string   the path to the kubeconfig file
  -n, --namespace string    the namespace scope
  -v, --version             version for k8s

Use "k8s [command] --help" for more information about a command.

with SPIN_EXPERIMENTAL=1:

><> SPIN_EXPERIMENTAL=1 spin k8s help
Manage apps running on Kubernetes

Usage:
  k8s [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  connect     connect to spin app locally
  delete      Delete app
  deploy      deploy spin app
  get         Display detailed information about an app
  help        Help about any command
  list        List apps
  logs        print the logs for a SpinApp
  scaffold    scaffold SpinApp manifest
  version     Display version information

Flags:
  -h, --help                help for k8s
      --kubeconfig string   the path to the kubeconfig file
  -n, --namespace string    the namespace scope
  -v, --version             version for k8s

Use "k8s [command] --help" for more information about a command.

Do we want to document this flag? Why or why not?

[endocrimes]

I would say no, for the time being - we don't really want folks who aren't actively working on SpinKube projects to actively interact with those commands until we're closer to figuring out the long term UX goals of various plugins. By documenting them we somewhat signup to actively supporting them (and being careful about breaking changes).

[tpmccallum]

If we did document this flag, we could deliberately only document it in one place. Thinking the Spin Plugin k8s CLI Reference might be the best place. We can differentiate running with SPIN_EXPERIMENTAL=1 in a separate section. This will allow us to remove those commands if they don't become part of the stable set of commands.
However, based on the comment above from @endocrimes and @bacongobbler's good point today about not waiting to reveal commands to users that we might take away, perhaps it is wise to only use the SPIN_EXPERIMENTAL=1 internally for convenience. As you pointed out @bacongobbler, we don't want to break an external user's CI/CD if we remove a command in the future.
Happy to close and not document (for the time being). Really happy you showed this though; very handy wrapper for development and testing.

[bacongobbler]

IMO I think it's fine to document the flag without documenting the commands associated with that flag. For example:

Experimental support

Experimental features are not ready for production. They are provided for test and evaluation purposes. They are not guaranteed to make it to production. Breaking changes can and will be made to these features while in development. Backwards compatibility is not guaranteed.

To enable experimental features, set the SPIN_EXPERIMENTAL environment variable:

export SPIN_EXPERIMENTAL=1

From that description, it is very clear that we are not signing up to support these features and that breaking changes are clearly part of the CLI experience.

We could go one step further and print a warning message to STDERR when these experimental features are being used.

@endocrimes does that allay your earlier concerns here, or do you still think this is not something we should document? I do share the same concerns because of how experiemental CLI feature support went with Helm 3 development. However I think that was a matter of the maintainers (including myself) not having enough of a backbone to say "no" to the client when they wanted us to address compatibility concerns with experimental features.

[justjoheinz]

Just my 2 ct: I am unhappy with the fact that e.g. spin kube deploy is used in the documentation (https://www.spinkube.dev/docs/topics/packaging/#deploying-spin-apps) without mentioning that it is an experimantal flag. I spend a good amount of time trying to figure out the required steps later on, and was not able to find the deploy step in spin kube --help, which confused me dearly.

I am all for documenting the commands, marking them clearly as experimental and let your users decide how to deal with that. You will never get feedback on your API if you hide it.