# Contributing

## Install

We use [pnpm](https://pnpm.io/) for this project. Install dependencies via:

```sh
pnpm install
```

## Build

```sh
pnpm run build
```

## Run tests

Test are written using [vitest](https://www.npmjs.com/package/vitest). To run tests, node 18 or later must be used.

```sh
pnpm run test

pnpm run test:watch
```

## Developing Groqd Playground

Run the following:

```sh
cp ./packages/playground-example/.env.example ./packages/playground-example/.env
```

And then add a Sanity project ID. 

Then, run `pnpm run dev:playground` from the root to start up all the necessary dev servers. From there you can:

- edit the editor in `packages/playground-editor`;
- edit the `groqd-playground` package from `packages/groqd-playground`;
- test the integration in `packages/playground-example`.

## Release

We use [changesets](https://github.com/changesets/changesets) to create package versions and publish them.

### Using changsets

Our official release path is to use automation to perform the actual publishing of our packages. The steps are to:

1. A human developer adds a changeset. Ideally this is as a part of a PR that will have a version impact on a package.
2. On merge of a PR our automation system opens a "Version Packages" PR.
3. On merging the "Version Packages" PR, the automation system publishes the packages.

Here are more details:

### Add a changeset

When you would like to add a changeset (which creates a file indicating the type of change), in your branch/PR issue this command:

```sh
$ pnpm run changeset
```

to produce an interactive menu. Navigate the packages with arrow keys and hit `<space>` to select 1+ packages. Hit `<return>` when done. Select semver versions for packages and add appropriate messages. From there, you'll be prompted to enter a summary of the change. Some tips for this summary:

1. Aim for a single line, 1+ sentences as appropriate.
2. Include issue links in GH format (e.g. `#123`).
3. You don't need to reference the current pull request or whatnot, as that will be added later automatically.

After this, you'll see a new uncommitted file in `.changesets` like:

```sh
$ git status
# ....
Untracked files:
  (use "git add <file>..." to include in what will be committed)
	.changeset/flimsy-pandas-marry.md
```

Review the file, make any necessary adjustments, and commit it to source. When we eventually do a package release, the changeset notes and version will be incorporated!

### Creating versions

On a merge of a feature PR, the changesets GitHub action will open a new PR titled `"Version Packages"`. This PR is automatically kept up to date with additional PRs with changesets. So, if you're not ready to publish yet, just keep merging feature PRs and then merge the version packages PR later.

## Documentation

We're using [Docusaurus](https://docusaurus.io/) to for the scaffolding of our documentation. The docs source files live in `website/docs` (so they can be viewed on GitHub), but the docusaurus site is built from `website`. To run the docs locally, run the following.

```shell
pnpm run dev:docs 
```

To contribute to the docs, make changes within the `docs` folder.