Skip to content

Commit f807cfb

Browse files
steveclaysteveclay
authoredOct 24, 2023
Merge pull request #389 from IBM-Cloud/dev
Release 1.1.2
2 parents cebcdbe + b469c05 commit f807cfb

File tree

5 files changed

+314
-133
lines changed

5 files changed

+314
-133
lines changed
 

‎.secrets.baseline

+17-7
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
"files": "^.secrets.baseline$|go.sum|.nancy-ignore",
44
"lines": null
55
},
6-
"generated_at": "2022-07-08T20:25:00Z",
6+
"generated_at": "2023-10-16T15:47:30Z",
77
"plugins_used": [
88
{
99
"name": "AWSKeyDetector"
@@ -138,15 +138,15 @@
138138
"hashed_secret": "3438d9111af8058916e075b463bd7a6583cbf012",
139139
"is_secret": false,
140140
"is_verified": false,
141-
"line_number": 254,
141+
"line_number": 265,
142142
"type": "Secret Keyword",
143143
"verified_result": null
144144
},
145145
{
146146
"hashed_secret": "53213c46677ac6f5576c44a4cbbdbe186d67cb00",
147147
"is_secret": false,
148148
"is_verified": false,
149-
"line_number": 256,
149+
"line_number": 267,
150150
"type": "Secret Keyword",
151151
"verified_result": null
152152
}
@@ -156,7 +156,7 @@
156156
"hashed_secret": "c8f0df25bade89c1873f5f01b85bcfb921443ac6",
157157
"is_secret": false,
158158
"is_verified": false,
159-
"line_number": 20,
159+
"line_number": 21,
160160
"type": "JSON Web Token",
161161
"verified_result": null
162162
}
@@ -212,7 +212,7 @@
212212
"hashed_secret": "e85f6eac7402c010fcea6b6d024a1875ac213f99",
213213
"is_secret": false,
214214
"is_verified": false,
215-
"line_number": 241,
215+
"line_number": 240,
216216
"type": "Secret Keyword",
217217
"verified_result": null
218218
}
@@ -345,18 +345,28 @@
345345
"verified_result": null
346346
}
347347
],
348+
"docs/interface_summary.md": [
349+
{
350+
"hashed_secret": "616e17a3f6182ce45befae8060d30bcb969a2897",
351+
"is_secret": false,
352+
"is_verified": false,
353+
"line_number": 261,
354+
"type": "Hex High Entropy String",
355+
"verified_result": null
356+
}
357+
],
348358
"docs/plugin_developer_guide.md": [
349359
{
350360
"hashed_secret": "616e17a3f6182ce45befae8060d30bcb969a2897",
351361
"is_secret": false,
352362
"is_verified": false,
353-
"line_number": 723,
363+
"line_number": 727,
354364
"type": "Hex High Entropy String",
355365
"verified_result": null
356366
}
357367
]
358368
},
359-
"version": "0.13.1+ibm.50.dss",
369+
"version": "0.13.1+ibm.61.dss",
360370
"word_list": {
361371
"file": null,
362372
"hash": null

‎bluemix/version.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ package bluemix
33
import "fmt"
44

55
// Version is the SDK version
6-
var Version = VersionType{Major: 1, Minor: 1, Build: 1}
6+
var Version = VersionType{Major: 1, Minor: 1, Build: 2}
77

88
// VersionType describe version info
99
type VersionType struct {

‎docs/interface_summary.md

+283
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,283 @@
1+
# IBM Cloud CLI Interface Summary
2+
3+
This summarizes the CLI interface guidelines as found in the [Plug-in Developer Guide](plugin_developer_guide.md).
4+
5+
## Name of the plug-in
6+
7+
Name of the plug-in should be a name that best describes the service the plug-in provides. Use the full name of the service in all lower case with a hyphen to replace space, for example 'my-service' ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#22-name-and-decription-of-plug-in-namespace-and-command)). Shorter aliases should be used to improve usability ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#11-register-a-new-plug-in)). Use commonly accepted shortened names of services as possible.
8+
9+
## Names of commands ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#22-name-and-decription-of-plug-in-namespace-and-command))
10+
11+
- For commands that list objects, use the plural of the object name, e.g. `ibmcloud iam api-keys`. If a plural will not work for some reason, use `list`, such as `ibmcloud app list`.
12+
- For commands that retrieve the details of an object, use the object name, e.g. `ibmcloud iam api-key`. If it does not work, use `show`, e.g. `ibmcloud app show`
13+
- Use common verbs in the names such as add, create, bind, update, delete …
14+
- Use `remove` to remove an object from a collection or another object it is associated with. Use `delete` to erase an object.
15+
16+
You have 2 options for the overall naming scheme of your commands:
17+
18+
Option 1: hyphenated commands ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#22-name-and-decription-of-plug-in-namespace-and-command))
19+
- Use lower case words and hyphen
20+
- Names should be at least 2 characters in length
21+
- Follow a “noun-verb” sequence (verb is the final part of the command)
22+
- Example: "object-create"
23+
24+
Option 2: using namespaced commands
25+
- follows the same rules as Option 1, only the delimiter is not hyphen, but space
26+
- Example: "object create"
27+
28+
## Command and namespace descriptions ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#22-name-and-decription-of-plug-in-namespace-and-command))
29+
30+
Use a sentence without subject to describe your plug-in or command. Limit the number of words to be less than 10 so that it can be properly displayed.
31+
32+
Correct description:
33+
34+
- `List all the virtual server instances.`
35+
- `Manage cloud database service.`
36+
37+
Incorrect description:
38+
- `Plugin to manage cloud database service.`
39+
- `Commands to manage cloud database service.`
40+
- `This command shows details of a sever instance.`
41+
42+
43+
## Messaging standards ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#21-global-specification))
44+
45+
1. Do NOT use "Please" in any message.
46+
Correct:
47+
<pre>First log in by running '<span class="yellow">ibmcloud login</span>'.</pre>
48+
Invalid:
49+
<pre>Please use '<span class="yellow">ibmcloud login</span>' to login first.</pre>
50+
51+
2. Capitalize the first letter for all sentences and short descriptions. For example:
52+
<pre>Change the instance count for an app or container group.</pre>
53+
<pre>-i Number of instances</pre>
54+
55+
3. Add "..." at the end of "in-progress" messages. For example:
56+
<pre>Scaling container group '<span class="cyan">abc</span>'...</pre>
57+
58+
4. Use "plug-in" instead of "plugin" in all places.
59+
60+
### Command formatting in output messages ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#22-name-and-decription-of-plug-in-namespace-and-command))
61+
62+
Use single quotation marks (') around the command name and options in output messages. The command itself should be yellow with **bold**. Where possible, place command names at the end of the sentence, not in the middle. For example:
63+
64+
```
65+
You are not logged in. Log in by running 'ibmcloud login'.
66+
```
67+
68+
### Entity formatting in output messages: ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#23-entity-name))
69+
70+
Add single quotation marks (') around entity names and keep the entity names in cyan with **bold**. For example:
71+
72+
```
73+
Mapping route 'my-app.us-south.cf.cloud.ibm.com' to CF application 'my-app'...
74+
```
75+
76+
77+
### Command Help ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#24-help-of-command))
78+
79+
- Use "-" for single letter flags, and "--" for multiple letter flags, e.g. `-c ACCOUNT_ID` and `--guid`.
80+
- All user input values should be shown as capital letters, e.g. `ibmcloud scale RESOURCE_NAME`
81+
- For optional parameters and flags, surround them with "[...]", e.g. `ibmcloud account orgs [--guid]`.
82+
- For exclusive parameters and flags, group them together by "(...)" and separate by "|".
83+
- Example: `ibmcloud test create (NAME | --uuid ID)`
84+
- "[...]" and "(...)" can be nested.
85+
- If a value accepts multiple type of inputs, it's recommended that for file type the file name should start with "@".
86+
- If a command has multiple paradigms and it's hard to describe them together, specify each of them in separate lines,
87+
e.g.
88+
```bash
89+
USAGE:
90+
ibmcloud test command foo.....
91+
ibmcloud test command bar.....
92+
```
93+
94+
The following gives an example of the output of the `help` command:
95+
96+
```
97+
NAME:
98+
scale - Change the instance count for an app or container group.
99+
USAGE:
100+
ibmcloud scale RESOURCE_NAME [-i INSTANCES] [-k DISK] [-m MEMORY] [-f]
101+
RESOURCE_NAME is the name of the app or container group to be scaled.
102+
OPTIONS:
103+
-i value Number of instances.
104+
-k value Disk limit (e.g. 256M, 1024M, 1G). Valid only for scaling an app, not a container group.
105+
-m value Memory limit (e.g. 256M, 1024M, 1G). Valid only for scaling an app, not a container group.
106+
-f Force restart of CF application without prompt. Valid only for scaling an app, not a container group.
107+
```
108+
109+
### Common options ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#212-common-options))
110+
111+
Users use multiple services. Consistency with option names simplifies this experience.
112+
113+
```
114+
OPTIONS:
115+
--force, -f Force the operation without confirmation
116+
--instance-id ID of the service instance.
117+
--output json Format output in JSON
118+
--resource-group-id value ID of the resource group. This option is mutually exclusive with --resource-group-name
119+
--resource-group-name value Name of the resource group. This option is mutually exclusive with --resource-group-id
120+
```
121+
122+
### Command Output
123+
#### Incorrect Usage ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#25-incorrect-usage))
124+
125+
When the user runs a command with the wrong usage (e.g. incorrect number of arguments, invalid option value, required options not specified, etc.), the message should be displayed and include help for the user for the command as below:
126+
127+
```
128+
Incorrect usage.
129+
NAME:
130+
scale - Change the instance count for an app or container group.
131+
USAGE:
132+
ibmcloud scale RESOURCE_NAME [-i INSTANCES] [-k DISK] [-m MEMORY] [-f]
133+
RESOURCE_NAME is the name of the app or container group to be scaled.
134+
OPTIONS:
135+
-i value Number of instances.
136+
-k value Disk limit (e.g. 256M, 1024M, 1G). Valid only for scaling an app, not a container group.
137+
-m value Memory limit (e.g. 256M, 1024M, 1G). Valid only for scaling an app, not a container group.
138+
-f Force restart of CF application without prompt. Valid only for scaling an app, not a container group.
139+
```
140+
141+
Provide any details possible to guide and inform the users. For example:
142+
143+
```
144+
Incorrect usage. The '-k' option is not valid for a container group.
145+
```
146+
147+
#### Command Failure ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#26-command-failure))
148+
149+
The failure message must start with "FAILED" in red with **bold**, followed by the detailed error message in a new line. A recovery solution should be provided, such as "Use another name and try again." or "Try again later."
150+
151+
In the message, explain the error and provide guidance on how to resolve the issue such as shown in the following output:
152+
153+
```
154+
Creating application 'my-app'...
155+
FAILED
156+
An application with name 'my-app' already exists.
157+
Use another name and try again.
158+
```
159+
160+
#### Command Success ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#27-command-success))
161+
162+
When a command is successful, the success message should start with "OK" in green with **bold** and followed by the optional details in new line like the following example:
163+
164+
```
165+
Creating application 'my-app'...
166+
OK
167+
Application 'my-app' was created.
168+
```
169+
170+
#### Warning Message ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#28-warning-message))
171+
172+
All of command warnings should be magenta with **bold** like:
173+
174+
```
175+
WARNING:
176+
If you enter your password as a command option, your password might be visible to others or recorded in your shell history.
177+
```
178+
179+
#### Important Information for the User ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#29-important-information))
180+
181+
The important information displayed to the end-user should be cyan with **bold**. For example:
182+
183+
```
184+
A newer version of the IBM Cloud CLI is available.
185+
You can download it from http://abc.abc.abc
186+
```
187+
188+
### User Input Prompts ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#210-user-input-prompt))
189+
190+
Prompting for user input:
191+
192+
1. The input prompt should consist of a prompt message and a right angle bracket '<span style="color: cyan">**>**</span>' with a trailing space.
193+
2. For a password prompt, the user input must be hidden.
194+
3. For a confirmation prompt, the prompt message should end with `[Y/n]` or `[y/N]` (the capitalized letter indicates the default answer) or `[y/n]` (no default, user input is required).
195+
196+
Following are examples:
197+
198+
#### Text prompt
199+
200+
```
201+
Logging in to https://cloud.ibm.com...
202+
Email>abc@example.com
203+
Password>
204+
OK
205+
```
206+
207+
#### Confirmation prompt
208+
209+
```
210+
Are you sure you want to remove the file? [y/N]> y
211+
Removing ...
212+
OK
213+
```
214+
215+
#### Choices prompt
216+
217+
```
218+
Select the plug-in to be upgraded:
219+
1. plugin1
220+
2. plugin2
221+
Enter a number (1)> 2
222+
223+
Upgrading 'plugin2'...
224+
```
225+
226+
#### Prompt override ("force" option)
227+
Users need a way to override prompts to allow the execution of non interactive scripts.
228+
229+
For the configrmation [y/N] prompt use the -f force option.
230+
231+
232+
### Table Output ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#211-table-output))
233+
234+
For a consistent user experience, developers of IBM Cloud CLI plug-ins should comply with the following table output specifications:
235+
236+
1. Table header should be bold.
237+
2. Each word in table header should be capitalized and translated.
238+
3. The entity name or resource name in table (usually the first column) should be cyan with bold.
239+
240+
The following is an example:
241+
242+
```
243+
Name Description
244+
my-app This is my application.
245+
demo-app This is a long long long ...
246+
description.
247+
```
248+
249+
### JSON Output ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#211-json-output))
250+
251+
Use flag `--output json` to show the json representation of resource(s) if the command is to list resources, or retrieve details of a resource. If this flag is used, don't show any informational messages or prompts but just the JSON string so that it can be easily parsed with other tools like jq. For example:
252+
253+
```
254+
$ibmcloud account orgs --output json
255+
[
256+
{
257+
"OrgGuid": "ef6e9345-2155-41bb-bd3d-ff7c10e5f071",
258+
"OrgName": "example-org",
259+
"Region": "us-south",
260+
"AccountOwner": "user@example.com",
261+
"AccountGuid": "8d63fb1cc5e99e86dd7229dddf9e5b7b",
262+
"Status": "active"
263+
}
264+
]
265+
```
266+
267+
When the output is an empty list the plugin should produce an empty json list (not null). For example if there were no account orgs:
268+
```
269+
$ibmcloud account orgs --output json
270+
[]
271+
```
272+
273+
If the output is expected to be an object but no object is returned the plugin should return the normal error: For example, if a service-id could not be found then an error is returned:
274+
```
275+
$ibmcloud iam service-id 15a15a0f-725e-453a-b3ac-755280ad7300 --output json
276+
FAILED
277+
Service ID '15a15a0f-725e-453a-b3ac-755280ad7300' was not found.
278+
```
279+
280+
### Globalization ([reference](https://github.com/IBM-Cloud/ibm-cloud-cli-sdk/blob/master/docs/plugin_developer_guide.md#7-globalization))
281+
282+
IBM Cloud CLI tends to be used globally. Both IBM Cloud CLI and its plug-ins should support globalization.
283+

‎go.mod

+3-3
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@ require (
1111
github.com/nicksnyder/go-i18n/v2 v2.2.0
1212
github.com/onsi/ginkgo v1.6.0
1313
github.com/onsi/gomega v1.10.0
14-
github.com/spf13/cobra v1.0.0
15-
github.com/spf13/pflag v1.0.3
14+
github.com/spf13/cobra v1.6.1
15+
github.com/spf13/pflag v1.0.5
1616
github.com/stretchr/testify v1.2.2
1717
golang.org/x/crypto v0.14.0
1818
golang.org/x/text v0.13.0
@@ -25,7 +25,7 @@ require (
2525
github.com/davecgh/go-spew v1.1.1 // indirect
2626
github.com/golang/protobuf v1.5.3 // indirect
2727
github.com/hpcloud/tail v1.0.0 // indirect
28-
github.com/inconshreveable/mousetrap v1.0.0 // indirect
28+
github.com/inconshreveable/mousetrap v1.0.1 // indirect
2929
github.com/mattn/go-isatty v0.0.5-0.20180830101745-3fb116b82035 // indirect
3030
github.com/pmezard/go-difflib v1.0.0 // indirect
3131
golang.org/x/net v0.17.0 // indirect

0 commit comments

Comments
 (0)
Failed to load comments.