# block-scripts

## Consolidate the pieces around block development for the Element ecosystem

### Installing `block-scripts`

Install via npm and save as a devDependency:

```bash
npm install --save-dev @volusion/block-scripts
```

### Using `block-scripts`

After installing the `block-scripts` package, it becomes an executable. Use it on its own or as an npm script in your block's `package.json` (recommended):

#### `block-scripts start`

Start the block server, using `rollup`

#### `block-scripts build`

Builds the block, also using `rollup`

#### `block-scripts lint`

Lints the block, using `eslint`

#### `block-scripts test`

Tests the block, using `jest`

### Developing

Clone the repo, change to the directory, and run `npm install`.

To use the executable, run `npm link` after running `npm run build`. Then, the executable `block-scripts` will be available to run in another terminal, as long as the same version of Node.js is loaded as the version present when you ran `npm link`.

#### The `.node-version` file

To ensure we're all using the same version of Node.js while developing, please use either [n](https://github.com/tj/n) or [nvm](https://github.com/creationix/nvm) to install the project's [Node.js version](/.node-version), and then install [AVN](https://github.com/wbyoung/avn), along with the relevant helper:

```bash
npm install -g avn

# If you're managing Node versions with NVM:
npm install -g avn-nvm

# If you're managing Node versions with n:
npm install -g avn-n
```

Then, set up AVN with

```bash
avn setup
```

and after following the on-screen instructions, you should be good to go — upon changing to this directory, you'll be automatically switched to use the correct version of Node.js, specified in the `.node-version` file.

### Releasing

Releases are automated using [release-please](https://github.com/googleapis/release-please). You do not need to manually bump versions or publish to NPM.

#### Commit message format

All commits must follow this format:

```
<type>: <JIRA-TICKET-ID> <description>
```

Examples:
- `feat: ET-4591 add support for new block config API`
- `fix: ET-4134 correct jest setup for jsdom environment`
- `chore: ET-4000 update dependencies`

A `commit-msg` hook (installed via `npm install`) will reject commits that don't match this format.

**Allowed types and their effect on versioning:**

| Type | Version bump | Use for |
|------|-------------|---------|
| `feat` | minor (x.**Y**.z) | New feature |
| `fix` | patch (x.y.**Z**) | Bug fix |
| `chore` | none | Maintenance, dependencies |
| `docs` | none | Documentation only |
| `refactor` | none | Code restructure, no behaviour change |
| `test` | none | Adding or updating tests |
| `build` | none | Build system changes |
| `ci` | none | CI/CD configuration |
| `perf` | patch | Performance improvement |
| `revert` | patch | Reverts a previous commit |

For a **major** version bump, add a `BREAKING CHANGE:` footer to your commit:

```
feat: ET-9999 redesign block config API

BREAKING CHANGE: configSchema prop renamed to schema
```

#### How releases work

1. Merge your PR to `master` with a conventional commit message.
2. The `Release Please` GitHub Action automatically opens (or updates) a **Release PR** that bumps the version in `package.json` and updates `CHANGELOG.md`.
3. When you're ready to release, merge the Release PR.
4. release-please creates a GitHub Release and git tag (e.g. `v2.5.0`).
5. The `Publish to NPM` GitHub Action triggers automatically and publishes the package to npmjs.com with a signed provenance attestation.