vsc-material-but-i-wont-sue-you/CONTRIBUTING.md

Contributing guidelines

Note: this document is intended as a draft, it will be updated soon

Requirements:

• Nodejs ^8.x
• Visual Studio Code
• GPG Tool

• Contributing guidelines
  • Requirements:
  • Installing and compiling source
    • Testing the theme
    • Adding new Material Theme commands
      • index.ts
        • Example of async exported function
        • Example of sync exported function
      • Using external "mini" modules
      • Register the command
      • Add to package.json
      • Build and run
      • Test your command
    • Adding new custom setting
  • Financial contributions
  • Credits
    • Contributors

Installing and compiling source

First you will have to install node_modules through npm

npm 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.

Testing the theme

To test the theme, you will have to go to the debug section, select the Launch Extension from debug and execute it.

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

export default async (): Promise<boolean> => {

    ...

Example of sync exported function

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

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:

  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

      {
        "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.

Credits

Contributors

Thank you to all the people who have already contributed to vsc-material-but-i-wont-sue-you!

Attribution

The code in this project was previously hosted at this url, but the original author has wiped all history of it, making it incredibly hard to credit him and the other original contributors. Full credit has been preserved in the git history here to our best ability.