chore: contributing update (#210)

This commit is contained in:
Alessio Occhipinti 2018-06-23 21:36:11 +02:00 committed by Mattia Astorino
parent c242d9a4b1
commit 06e4f33313

View file

@ -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!