Contributing to Meshery CLI
mesheryctl is written in Golang or the Go Programming Language. For development use Go version 1.15+.
Meshery CLI Reference Documents
Mechanics of Contributing
/mesheryctl folder contains the complete code for
mesheryctl. Fork and clone the Meshery repo.
cd mesheryctl to change directory mesheryctl’s source.
After making changes, run
make in the
mesheryctl folder to build the binary. You can then use the binary by, say,
./mesheryctl system start.
mesheryctl uses the Cobra framework. A good first-step towards contributing to
mesheryctl would be to familiarise yourself with the Cobra concepts. For manipulating config files,
mesheryctl uses Viper.
Model and Configuration Data
struct is maintained in the
mesheryctl/internal/cli/root/config/config.go file. These are updated and should be used for getting the Meshery configuration.
mesheryctl uses golangci-lint. See the .github/workflow/ci.yaml for syntax used during Meshery’s build process.
Unit test code coverage reports can be found - tbd.
Meshery CLI Style Guide
These guidelines are a collection of principles and conventions that need to be followed while designing mesheryctl commands.
mesheryctl might be the interface that the users first have with Meshery. As such,
mesheryctl needs to provide a great UX.
The following principles should be taken in mind while designing
1. Consistency is quality.
- Consistency of interaction drives a quality user experience. Whether that experience is delightful or painful is a related, but separate consideration. Meshery’s behavior of user interactions should be consistent even when their user experience is poor.
2. Intuitive user experiences feel natural to users.
- When being designed, each of Meshery’s user experiences should be examined first from the user’s perspective. Design user experiences that are familiar.
3. Design for brevity.
- Avoid long commands with chained series of flags.
4. Design with automated testing in mind.
- Provide possibility to specify output format as json (-o json) for easy inspection of command response.
Part of delivering a great user experience is providing intuitive interfaces. In the case of
mesheryctl takes inspiration from and delivers similar user experiences as popular CLIs do in this ecosystem, like
docker. Here is relevant
kubectl information to reference - Kubectl SIG CLI Community Meeting Minutes, contributing to kubectl, code.
Command structure and command behavior should be designed in such a way that they are intuitive. Users should ideally be able to understand what a command is used for without having to extensively go through the documentation. For example,
mesheryctl pattern apply -f <pattern name> requires no further clarification as it is evident that the command will apply the pattern specified.
Consistency is key when designing intuitive interfaces. Although
mesheryctl perf run -f <performance profile name> may sound more intuitive, users who are experienced in using the CLI will prefer the consistant verb
run. This will also ensure a consistent command language making memorizing easier.
Consistency should also be enforced when chaining commands and using flags. For example, if
mesheryctl pattern has a
view command and has an
--output flag, then, similar commands like
mesheryctl perf should also support the same commands and flags and provide a consistent user experience.
Rational defaults overriden with flags
Default behaviour should be optimised for what users will need to do most of the time.
These assumed defaults should be easily overriden by the user with flags.
mesheryctl system context create <context name> assumes a default platform for the created context. But this can be easily overriden with the
User Experience: GUI vs CLI
Ideally, all functionaly provided in Meshery UI should be available to users via CLI (in
mesherctl). Meshery strives for parity of functionality between it’s two clients. For example, viewing a performance profile in the GUI and with
mesheryctl system perf view <profile name> in the CLI should show the same data.
Command line interfaces offer less context to the user, which makes them inherently less intuitive compared to graphical user interfaces. Both of these user interfaces, however, are the same in that they are both clients of Meshery Server. Both clients are a user experience and as such, to be attended to in this way. The following considerations should be accounted for when designing
- Provide only relevant output. Use “debug” logs that can be accessed with
--verboseflag wherever needed.
- Add headers to output to give context to the user.
- As mentioned above, similar commands should behave similarly.
- Confirm steps for risky commands. For example, use the
AskForConfirmationfunction which will prompt the user to type in “yes” or “no” to continue.
- Anticipate user actions. If the user creates a new context with
mesheryctl system context createthen the next action might be
mesheryctl system startto start Meshery ot
mesheryctl system context switchto switch context names.
- Anticipate user errors. For example, if the user types in
mesheryctl system satrt, using the inbuilt features with the cobra library, we can correct it to
startand alert the user.
If you are working on a new command or adding a new feature on an existing command, it is recommended to setup a design spec so that other contributors can weigh in on the design before you start to code. Broader features should have a design spec made in Google Doc using this template. For small changes, communicating over the issue tracker or the discussions will be helpful.
When designing for the command line interface, ask and consider the following questions.
What the command does
- What makes sense to do from a terminal? What doesn’t?
- What might people want to automate?
- What is the default behavior? What flags might you need to change that behavior?
- What might people try and fail to do and how can you anticipate that?
What the command is called
- What should be the command language? (
mesheryctl <command> <subcommand> [args] [flags] [value])
- What should be a command vs a flag?
- How can you align the language of the new command with the existing commands?
What the command outputs
- How can you make the GUI and the CLI outputs similar?
- What should be outputted normally and what falls into debug logs?
How you explain your command
You will need to provide a short and long description of the command for the help pages and also for the Meshery Documentation.
- Contributing to Meshery UI
- Meshery Contributing Guidelines
- Contributing to Meshery Docs
- Contributing to Meshery CLI
- Contributing to Meshery Adapters
- Contributing to Meshery using git