# Contributing to onedark.vim

Please read this document before submitting a Pull Request.

**Pull Requests containing changes to files in the `autoload/` or `colors/` directories without corresponding changes to files in the `build/templates` directory will _not_ be merged.**

## Build System

### Background Information

onedark.vim's shared color definitions file `autoload/onedark.vim` and its companion Xresources color palette file are built using a rudimentary templating and build system that allows color definitions to live in a single, central file. (Additional terminal color palette files are themselves generated from the template-produced Xresources file.)

The basic idea is that these files are generated by a build tool that substitutes color values into templates that live in `build/templates`.

Here are the locations of the files that are generated by the build system, along with the locations of the corresponding templates they are generated from:

| Theme Location              | Template Location                       |
| --------------------------- | --------------------------------------- |
| `autoload/onedark.vim`      | `build/templates/autoload.template.vim` |
| `term/One Dark.Xresources`  | `build/templates/One Dark.Xresources`   |
| `term/One Dark.itermcolors` | `build/templates/One Dark.itermcolors`  |
| `term/One Dark.terminal`    | `build/templates/One Dark.terminal`     |
| `term/One Dark.alacritty`   | `build/templates/One Dark.alacritty`    |
| `term/One Dark.colorscheme` | `build/templates/One Dark.colorscheme`  |

### Configure It

1. Install [Node.js](https://nodejs.org/en/) (Installing via [nvm](https://github.com/creationix/nvm) or [homebrew](https://brew.sh) are both better options than the official Node.js installer.)

2. Run the following from within the root of this repository. This will install the build system's dependencies and will automatically configure a Git pre-commit hook that runs `npm test` (see below).

```bash
> npm install
```

That's it!

### Use It

The build system consists of a single Node.js script, `build/build.js`, which supports two commands:

- Running `./build/build.js` or `npm run build` generates theme files from the templates, **overwriting changes to the theme files without confirmation.**
- Running `./build/build.js check` or `npm test` checks that the theme files match the template-generated output, **without modifying theme files**. This command ensures that the theme files perfectly match the templates they are generated from, which is useful for detecting changes that were made to generated theme files but that should have been made in the templates.
- In addition to running `./build/build.js check`, `npm test` also runs linting and style checks on certain files to catch and prevent simple problems and stylistic inconsistency. If `npm test` reports any issues, many reported issues can be automatically fixed by running `npm run lint:fix`.)

The basic development workflow looks like this:

1. Make changes to the appropriate template files in `build/templates`, then run `npm run build`.

2. Commit your changes with Git. `npm test` will automatically run before your commit is finalized. If the test fails, fix any inconsistencies between the template files and theme files (or linting/style errors if applicable), then try committing again.

## Style Guidelines

Please match the existing comment and whitespace style in all template files.

For the "Language-Specific Highlighting" portion of onedark.vim, blocks for each language should be organized alphabetically ("Markdown" comes before "PHP").

All code changes should pass against the included linting and style checks. These checks are run via [husky](https://www.npmjs.com/package/husky) and [lint-staged](https://www.npmjs.com/package/lint-staged) when you attempt to commit changes. You can manually check for linting and stylistic issues by running `npm test`, and many reported issues can be automatically fixed by running `npm run lint:fix`.

## Thanks!

Thanks very much for contributing to onedark.vim!