# Get Started
Read this before you submit your first contribution.

## How to Contribute

Take care to read all contributions guidelines before you begin!

1. Learn how to [contribute to open source](https://opensource.guide/how-to-contribute/).
2. Follow a [step-by-step guide](https://github.com/firstcontributions/first-contributions) to practice your first contribution.
3. Locate an [open issue on GitHub](https://github.com/skeletonlabs/skeleton/issues). Post a comment letting us know you wish to volunteer.
4. Optionally, you may coordinate efforts on the `#contributors` channel within [Discord](https://discord.gg/EXqV7W8MtY).
5. A member of the Skeleton team will assign the issue to you and help outline requirements.
6. Complete the work and submit a pull request per the requirements on this page.

> NOTE: non-trivial PRs submitted without our prior consent will be denied. Repeat offenders will be blocked.

## Using PNPM

Skeleton makes use of [PNPM](https://pnpm.io/) and [PNPM workspaces](https://pnpm.io/workspaces) to maintain all projects within the Skeleton monorepo.

1. [Install PNPM](https://pnpm.io/installation) on your local computer.
2. [Fork the Skeleton monorepo](https://github.com/skeletonlabs/skeleton) via the option on GitHub.
3. Use Git to clone the forked project to your local machine.
4. Run `pnpm i` from the root to install the required dependencies.
5. Point your terminal at one of the `/sites`, `/packages` or `/playgrounds` projects detailed below.
6. Run `pnpm dev` to start a local dev server for each project.

> NOTE: Make sure you're running PNPM version `9.5.0` or higher to ensure support for [PNPM catalogs](https://pnpm.io/catalogs). You can check your version with `pnpm --version`.

### Adding Dependencies

As a courtesy, please consult with Skeleton maintainers before adding dependencies. Third-party dependencies come with some level of risk, and we may be able to offer alternatives that limit the scope of changes.

Dependencies may be installed using the standard `pnpm i` command. However, in some cases it may be beneficial to maintain a uniform version shared across multiple projects or within each `package.json`. For this we can make use of [PNPM Catalogs](https://pnpm.io/catalogs).

The main version is maintained in the monorepo root in `pnpm-workspace.yaml`:

```yaml
catalog:
	# ...
	<package>: <version>
```

Use the following convention to link each project's dependency to the shared Catalog version:

```shell
pnpm add <package>@catalog:
```

## Monorepo Structure

### Sites

Public facing websites that are deployed and hosted for users to browse.

| Path                         | Description                           |
| ---------------------------- | ------------------------------------- |
| `/sites/skeleton.dev`        | The production documentation website. |
| `/sites/themes.skeleton.dev` | The Skeleton themes generator website |

### Packages

Modular Skeleton packages distributed via NPM.

| Path                        | Description                                                                |
| --------------------------- | -------------------------------------------------------------------------- |
| `/packages/skeleton`        | The Skeleton core package, contains Skeleton's Tailwind-specific features. |
| `/packages/skeleton-react`  | The Skeleton React package, contains Skeleton React components.            |
| `/packages/skeleton-svelte` | The Skeleton Svelte package, contains Skeleton Svelte components.          |
| `/packages/skeleton-common` | The Skeleton common package, contains shared internal only utilities.      |
| `/packages/cli`             | The Skeleton CLI, contains Skeleton's migrations.                          |

## Playgrounds

Isolated sandbox environments for developing, testing and experimenting.

| Path                           | Description                                           |
| ------------------------------ | ----------------------------------------------------- |
| `/playgrounds/skeleton-svelte` | A SvelteKit playground for testing the Svelte package |
| `/playgrounds/skeleton-react`  | A NextJS playground for testing the React package     |

## Branch

Create and target all pull requests against the `main` branch unless otherwise instructed.

| Branch | Description                                        | Pull Requests                                  |
| ------ | -------------------------------------------------- | ---------------------------------------------- |
| `main` | Represents the release branch of the all projects. | <Check size={16} className='inline' /> Allowed |

### PR Branch Conventions

Please use the following naming convention when creating your pull request.

| Branch      | Role                                  |
| ----------- | ------------------------------------- |
| `docs/*`    | When updating the documentation site. |
| `feature/*` | When implementing a new feature.      |
| `task/*`    | When implementing a small task.       |
| `bugfix/*`  | When implementing a fix for a bug.    |

Keep branch names short and semantic, and use snake-case to separate words.

```
docs/get-started-typo-fix
bugfix/accordion-render-issue
```

## Documentation Schema

Before your first run of the `/sites/skeleton.dev` documentation project, make sure to run `pnpm generate:types` at least one time. This will generate the assets required to populate API Reference tables on each component's documentation page.

## Changesets

[Changesets](https://github.com/changesets/changesets) are used to automatically generate the changelog for each release.

- Any contributions made within `/packages` _must_ contain a Changeset
- Any contributions made within `/sites` should <u>not</u> include a Changeset.

Follow these instructions to generate a changeset:

1. Make sure you're within your local pull request feature branch.
2. Navigate to the root of the Skeleton monorepo.
3. Run `pnpm changeset` to trigger the Changeset CLI.
4. Follow the instructions when prompted.
5. Changeset are added as `.md` files within the `.changeset/` directory.
6. You may edit or revise a Changeset before your PR is merged.

Changesets use semantic versioning. We recommend the following convention.

| Version | Role                                        |
| ------- | ------------------------------------------- |
| `major` | Do not use. Reserved for maintainers only.  |
| `minor` | For notable changes, such as a new feature. |
| `patch` | For small changes, such as a fixing a bug.  |

Changeset descriptions will appear verbatim on the [Changelog](https://github.com/skeletonlabs/skeleton/blob/dev/packages/skeleton/CHANGELOG.md). Keep it short, semantic, and and include the same [branch prefix](/docs/resources/contribute/get-started#pr-branch-conventions).

```mdx
---
'@skeletonlabs/skeleton-svelte': minor
---

feature: Added a new Avatar component.
```

## Tooling

Skeleton makes use of the following technology to improve the developer experience. It's recommended you run these tools before flagging the PR as "ready for review" on GitHub.

### Root Commands

Run the following commands in the monorepo root. Each will run recursively for supported packages.

- `pnpm format` - Formats the monorepo using [Prettier](https://prettier.io/).
- `pnpm lint` - Finds (and attempts to fix) any issues within the monorepo using [ESLint](https://eslint.org/).
- `pnpm test` - Runs all unit tests using [Vitest](https://vitest.dev/).
- `pnpm check` - Runs framework specific diagnostics, such as [Svelte Check](https://svelte.dev/docs/cli/sv-check), [Astro Check](https://docs.astro.build/en/reference/cli-reference/#astro-check), etc.

### Local Commands

Additionally, you may also run the local instance of each command. Consult the local `package.json` for available options. For `format` and `lint` commands, use the following syntax to draw from the root `package.json`:

```shell
pnpm -w <command>
```

### VS Code Extensions

We recommend the use of [VSCode](https://code.visualstudio.com/) for contributions, and the following VSCode extensions.

- [Tailwind](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
- [Astro](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode)
- [MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx)
- [Svelte](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode)
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)