-
Notifications
You must be signed in to change notification settings - Fork 326
Spec checklist
Albert-Jan Schot edited this page Feb 11, 2022
·
4 revisions
- command name follows the naming convention of
service command (subcommand) verb
- command name aligns as much as possible with existing commands and groups
- command name ends with a verb
- all nouns in the command name are singular
- options follow the naming convention of not repeating the last noun, eg.
spo web get --url
instead ofspo web get --webUrl
- required options are denoted as
--required <required>
- optional options are denoted as
--optional [optional]
- shorts use a single dash followed by a single letter, eg
-i
instead of-id
- command doesn't use global shorts like
-h
or-o
- all options have a clear description that indicates their purpose
- if the option belongs to a set, it clearly indicates all options in a set, eg.
Specify appId, objectId or name
- if the option expects predefined values (enum), it lists all allowed values
- if there are additional considerations for implementation/usage they are included in the spec and later in the docs
- if the command requires additional scopes that aren't available in the CLI, these scopes are included in the spec
- if the command uses a preview API, it explicitly mentions it in the spec and later in the docs
- if the command return multiple values the specs explains what properties are returned for csv and text output
- the enhancement doesn't introduce breaking changes. We consider a change breaking when we:
- rename a command
- rename an option
- change the command output other than add new properties
- the command implementation switches from
v1.0
to abeta
Microsoft Graph endpoint even if the output would not change
- if the enhancement is a breaking change, it's labeled as a breaking change and the PR must open to the next major version branch not main. Spec mentions this explicitly
- if the enhancement introduces new options they're included in the spec following the same guidelines as for new commands
- if the enhancement introduces new functionality (new options or considerations), it explicitly mentions that docs should be updated in the PR