You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/docs/contribute/contributing-guide.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,7 +29,7 @@ Typos are embarrassing! Most PRs that fix typos will be accepted immediately. To
29
29
-**DO** keep discussions focused. When a new or related topic comes up, it's often better to create a new issue than to side-track the conversation.
30
30
-**DO NOT** submit PRs for coding style changes. These changes can cause unnecessary conflicts and make the review process more complicated.
31
31
-**DO NOT** surprise us with big PRs. Instead, file an issue and start a discussion so we can agree on a direction before you invest a large amount of time.
32
-
-**DO NOT** commit code you didn't write. We encourage you to contribute your own work to maintain
32
+
-**DO NOT** commit code you didn't write. We encourage you to contribute your own work to maintain project quality and integrity.
Copy file name to clipboardExpand all lines: docs/docs/contribute/new-command/build-command-logic.mdx
+15-5Lines changed: 15 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -46,11 +46,21 @@ class SpoGroupGetCommand extends SpoCommand {
46
46
exportdefaultnewSpoGroupGetCommand();
47
47
```
48
48
49
+
Each command in the CLI for Microsoft 365 follows a consistent class naming convention to ensure clarity and maintainability. The command class name is based on the command's name and follows PascalCase. It is composed of the command's hierarchy segments joined together, followed by the suffix Command. For example, for the command `spo group get`, the class name would be `SpoGroupGetCommand`.
50
+
51
+
:::warning
52
+
53
+
To prevent an uncontrolled expansion of command names, we maintain a dictionary of approved command words that can be used when defining a command. This dictionary is located in the [`eslint.config.mjs`](https://github.com/pnp/cli-microsoft365/blob/main/eslint.config.mjs) file.
54
+
55
+
If a desired command name includes a word that isn't in the approved list, that word should be added to the dictionary to allow the automated workflow to pass successfully.
56
+
57
+
:::
58
+
49
59
Depending on your command and the service for which you're building the command, there might be a base class that you can use to simplify the implementation. For example, for SPO, you can inherit from the [SpoCommand](https://github.com/pnp/cli-microsoft365/blob/main/src/m365/base/SpoCommand.ts) base class. This class contains several helper methods to simplify your implementation.
50
60
51
61
### Include command name
52
62
53
-
When you create the minimum file, you'll get an error about a nonexistent type within `commands`. This is correct because we haven't defined the name of the command yet. Let's add this to the `commands` export located in `src/m365/spo/commands.ts`:
63
+
When you create the minimum file, you'll get an error about a nonexistent type within `commands`. This is correct because we haven't defined the name of the command yet. Let's add this to the `commands` export located in `src/m365/spo/commands.ts`. Note that all commands in this file are sorted strictly **alphabetically**.
awaitlogger.logToStderr(`Retrieving information for group in site at ${args.options.webUrl}...`);
274
+
awaitlogger.logToStderr(`Retrieving information for group in site at '${args.options.webUrl}'...`);
265
275
}
266
276
267
277
// Command implementation goes here
@@ -317,4 +327,4 @@ If this command fails, be sure to check if your environment has been set up corr
317
327
318
328
## Next step
319
329
320
-
Now that the command is fully functional we will need to add some tests to ensure that the command works as expected. This will be explained in the next chapter: [Unit Tests](./unit-tests.mdx).
330
+
Now that the command is fully functional we will need to add some tests to ensure that the command works as expected. This will be explained in the next chapter: [Unit Tests](./unit-tests.mdx).
Copy file name to clipboardExpand all lines: docs/docs/contribute/new-command/unit-tests.mdx
+5-3Lines changed: 5 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -46,7 +46,7 @@ With the basis of `Mocha` ready, we will set up the basis for `Sinon`. This will
46
46
47
47
Before we start with the test suite, we want to make sure that the basic functions like `telemetry` and `authentication` are ignored. This will make it so functions like `restoreAuth` return a response when our code, `group-get.ts`, requires it.
Copy file name to clipboardExpand all lines: docs/docs/contribute/new-command/writing-the-docs.mdx
+20-24Lines changed: 20 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,7 +28,7 @@ npm start
28
28
29
29
With our help file created, we can start writing down the command specs. A help file for a command will have at minimum the following topics. The command name as the title, a description, the usage, options, a few examples on how to use them, and a sample response output. We'll start with the `title`, `description`, and `usage`.
Most commands will have unique options but every command will make use of our global options. This can be achieved by including `<Global />` under the heading options. This will include the global options in the help page. Before we can use the global options tag, we need to import it from `/docs/cmd/_global.mdx`. This can be done by adding the following import at the top of your help file.
@@ -116,7 +116,7 @@ import TabItem from '@theme/TabItem';
116
116
117
117
As they say, a picture is worth a thousand words, same goes for examples of code. This is why we strive to add several examples for each command with some logical option data. This gives more insight to users on how they can implement the command in their script. We require at least 2 examples per command (if possible).
@@ -147,7 +147,7 @@ Some pointers to keep in mind when including sample data in our examples.
147
147
148
148
We include the response output for each command to give more insight into what users can expect from this command. This is especially useful for commands that return a lot of data. We include the response output in the following formats: JSON, Text, CSV, and Markdown. This is done by using the `Tabs` component from the Docusaurus library. This component allows us to include multiple tabs with different content. The `TabItem` component is used to include the content for each tab. The `value` attribute is used to specify the name of the tab. Make sure to include the `Tabs` and `TabItem` imports at the top of your help file.
@@ -233,30 +233,26 @@ import TabItem from '@theme/TabItem';
233
233
Each different verb of command can return a different type of response. This means that a `get` command will return a single object response while a `list` command returns an object list. Below you'll find different examples for different scenarios.
Some general pointers to keep in mind when writing the verbose output.
262
258
@@ -277,7 +273,7 @@ It is possible that a command needs to include some more information. Some addit
277
273
278
274
This heading can be used to communicate some important details about your command to the user. This could be to communicate that you used a preview API or that a number option is specified as a 0-based index. Remarks headings are most commonly placed between the headings `Options` and `Examples`.
pageNumber is specified as a 0-based index. A value of 2 returns the third page of items.
@@ -287,15 +283,15 @@ pageNumber is specified as a 0-based index. A value of 2 returns the third page
287
283
288
284
Here we can include some links to the APIs we used in the command or some documentation pages that explain the command usage in more detail. This isn't required but it is nice to have. This heading is most commonly placed at the end of your help page.
- SharePoint home sites: a landing for your organization on the intelligent intranet: https://techcommunity.microsoft.com/t5/Microsoft-SharePoint-Blog/SharePoint-home-sites-a-landing-for-your-organization-on-the/ba-p/621933
294
290
```
295
291
296
292
## Include into the command navigation
297
293
298
-
Now that your page is finished, we need to make it available from the command navigation, most commonly found on the left side of the page. To include this, we need to edit the file `sidebars.js` found in the folder `src/config`. Navigate through the section `commands` and locate your commands command group. Here you can add the path to your new help page.
294
+
Now that your page is finished, we need to make it available from the command navigation, most commonly found on the left side of the page. To include this, we need to edit the file `sidebars.js` found in the folder `src/config`. Navigate through the section `commands` and locate your commands command group. Here you can add the path to your new help page. Note that all navigation nodes are somewhat sorted alphabetically.
0 commit comments