# Contributing

Contributions are very much welcomed! Please read this guide to help you get started.

## General Development

### Install Dependencies

```bash
npm install
```

### Run Tests

```bash
npm test
```

Note that `npm run build` will run prior to tests and the unit tests are run against the compiled source
instead of the original source code.

### Committing & Pushing Changes

When you commit changes [Prettier](https://prettier.io/) will run automatically.

If you want to manually run prettier you can use `npm run prettier:check` or `npm run prettier:fix`.

When you push changes `npm test` will automatically run. All tests need to pass for a push to be successful.

## New Features

We welcome contributions to the code base, please feel free to [open an issue](https://github.com/flmnt/graphemer/issues/new) to discuss ideas or fork the repository and open a pull request.

If you do open a pull request, please ensure all tests are passing, and you have listed your changes in the [CHANGELOG](https://github.com/flmnt/graphemer/blob/master/CHANGELOG.md).

### Adding Functionality

If you have an idea for new functionality please create a new issue so we can discuss design of the new feature.

Once we have agreed an approach please fork the repository, make your chnages and open a pull request.

We aim to respond quickly, but please be aware it's a small team maintaining this library.

### New Unicode Version Adoption

We aim to keep up to date with the latest Unicode versions, however, if we are late in releasing a new version feel free to follow the steps below and create a pull request with an updated Unicode version. You can find out information about the [latest Unicode version here](http://www.unicode.org/versions/latest/).

**Step 1**

We need to configure our test suite to test for the latest characters.

First, download the latest Unicode test data. If you're using a Mac and don't have `wget` you can installed it with Homebrew: `brew install wget`

```bash
wget https://www.unicode.org/Public/UCD/latest/ucd/auxiliary/GraphemeBreakTest.txt -O tests/GraphemeBreakTest.txt
```

Then run the test suite. It should pass.

**Step 2**

Next we need to download the latest break properties and emoji data.

```bash
wget https://www.unicode.org/Public/UCD/latest/ucd/auxiliary/GraphemeBreakProperty.txt -O scripts/GraphemeBreakProperty.txt

wget https://www.unicode.org/Public/UCD/latest/ucd/emoji/emoji-data.txt -O scripts/emoji-data.txt
```

**Step 3**

Now we need to generate the code to identify break properties. Run the generator script and copy the output to your clipboard.

```bash
node ./scripts/generate-grapheme-break.js | xclip    # linux
node ./scripts/generate-grapheme-break.js | pbcopy   # osx
```

Paste the copied code into the `getGraphemeBreakProperty()` method in `src/Graphemer.ts`.

```javascript
  static getGraphemeBreakProperty(code: number): number {
    // Grapheme break property taken from:
    // https://www.unicode.org/Public/UCD/latest/ucd/auxiliary/GraphemeBreakProperty.txt
    // and generated by
    // node ./scripts/generate-grapheme-break.js

    /* PASTE CODE HERE */

    // all unlisted characters have a grapheme break property of "Other"
    return CLUSTER_BREAK.OTHER;
  }
```

Save the file.

**Step 4**

Next we need to generate the code to identify emoji properties. Run the generator script and copy the output to your clipboard.

```bash
node ./scripts/generate-emoji-extended-pictographic.js | xclip    # linux
node ./scripts/generate-emoji-extended-pictographic.js | pbcopy   # osx
```

Paste the copied code into the `getEmojiProperty()` method in `src/Graphemer.ts`.

```javascript
  static getEmojiProperty(code: number): number {
    // emoji property taken from:
    // https://www.unicode.org/Public/UCD/latest/ucd/emoji/emoji-data.txt
    // and generated by
    // node ./scripts/generate-emoji-extended-pictographic.js

    /* PASTE CODE HERE */

    // unlisted emoji treated as a break property of "Other"
    return CLUSTER_BREAK.OTHER;
  }
```

Save the file.

**Step 5**

Run `npm run prettier:fix` to format the code.

Run `npm test` to check everything is working.

Then commit and push your code.

## Bug Fixes

If you notice a bug in the code, please report it via a [new issue](https://github.com/flmnt/graphemer/issues/new). And even better, try and fix it via a pull request!

We'll do our very best to support anyone looking to fix and bugs. Your help is very much appreciated.

If you do open a pull request, please ensure all tests are passing, and you have listed your changes in the [CHANGELOG](https://github.com/flmnt/graphemer/blob/master/CHANGELOG.md).

## Publishing

When updates are merged via a pull request, we will create a new release.

This automatically publishes the library to NPM.