From 06e4f333139e51b572d915436b3e280853da2183 Mon Sep 17 00:00:00 2001
From: Alessio Occhipinti <LasaleFamine@users.noreply.github.com>
Date: Sat, 23 Jun 2018 21:36:11 +0200
Subject: [PATCH] chore: contributing update (#210)

---
 CONTRIBUTING.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 81 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 91beafb..3d9fc68 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,7 +4,7 @@
 
 ## Requirements:
 
-* Nodejs ^6.x
+* Nodejs ^8.x
 * Visual Studio Code
 * GPG Tool
 
@@ -32,7 +32,7 @@ yarn install
 
 To compile to the source code, you have to execute the build task through visual studio code.
 First you need to invoke to quick command (on MacOS `⌘P`, while on Linux/windows is `ctrl+p`)
-then type `task build` and wait until vsc will have finished the task.
+then type `task build` and wait until VSC will have finished the task.
 
 ### Testing the theme
 
@@ -40,6 +40,82 @@ To test the theme, you will have to go to the debug section, select the *Launch
 
 ### Adding new Material Theme commands
 
+Material Theme commands are located inside the `extensions/commands` directory. They are split by folders so you can find a single specific `index.ts` file inside a `command` folder. This is a patter choice: so you can add related command helpers inside that folder.
+
+#### index.ts
+
+The main file must return a `function`. The `function` can be `async` or `sync`.
+
+We want to make this clear, so the `async` declaration must be present even if you want to use `then()` for chaining inside the `function`.
+
+##### Example of `async` exported `function`
+
+```js
+export default async (): Promise<boolean> => {
+
+    ...
+```
+
+##### Example of `sync` exported `function`
+
+```js
+export default (): boolean => {
+
+    ...
+```
+
+#### Using external "mini" modules
+
+We encourage you to split up your command in other small modules so they can be **tested** more easily and outside of the context.
+
+#### Register the command
+
+You must register the new command to execute it when it's called by the user.
+
+Firstly add the command to our commands `extensions/commands/index.ts`
+
+```js
+export {default as awesomeCommand} from './awesome-command';
+```
+
+Commands are registered within the `extensions/material.theme.config.ts` file.
+
+Just add a new registration after the others that will run your command:
+
+```js
+
+  Commands.registerCommand('materialTheme.awesomeCommand', () => ThemeCommands.awesomeCommand());
+
+```
+
+#### Add to package.json
+
+When you are ready to test your new command you must add its declaration within the `package.json`. The command **must be prefixed with** `materialTheme.` prefix.
+
+As the others your command will look like this:
+
+Level: `contribute.commands -> Array`
+```json
+
+      {
+        "command": "materialTheme.awesomeCommand",
+        "title": "Awesome Title For Command",
+        "category": "🎨 Material Theme"
+      }
+
+```
+
+#### Build and run
+
+Now you can re-build the theme and just run the debug, you will see your command in the command list of VSCode just searching for its title.
+
+#### Test your command
+
+A test suite is currently in developing. Update soon.
+
+
+### Adding new custom setting
+
 Soon(ish)®
 
 ### Adding new icons
@@ -48,10 +124,12 @@ Soon(ish)®
 
 * Add the reference to that icon to the `~/src/icons/partials/fileNames.js` or if your icon is referred to a directory adds the reference to the `~/src/icons/partials/folderNames.js` file, otherwise to `~/src/icons/partials/fileExtensions.js` if is referred to a file extension.
 
-* If you want to make the icon sensitive to be accented, modify the `~/extensions/defaults.json` file, adding the icon definition to the `accentableIcons` array (e.g. ["_folder_open", "_folder_open_build"]) and the path to the `icons.theme.iconDefinitions` object. The same applies to variants (the variant icons array is called "variantsIcons")
+* If you want to make the icon sensitive to be accented, modify the `~/extensions/defaults.json` file, adding the icon definition to the `accentableIcons` array (e.g. ["_folder_open", "_folder_open_build"]) and the path to the `icons.theme.iconDefinitions` object. **The same applies to variants (the variant icons array is called "variantsIcons")**
 
 * Execute the build command.
 
+* Start the debug
+
 * Enjoy your new icons in Material Theme, and don't forget to pull request!