# Pull Request Guidelines

Keep each pull request focused on a clear improvement to ipa-hub. Explain the problem, the resulting behavior, and how you verified it so reviewers can assess the change.

## Development

Start with [Setting Up a Dev Environment](https://ipa-hub.giladgd.com/docs/guide/development.md) to clone the repository, install dependencies, and run `npm run dev:setup`.

Follow the surrounding TypeScript style and use the configured ESLint formatter. Keep runtime npm dependencies empty; build tools and bundled frontend dependencies belong in `devDependencies`. Add tests for new behavior and fixes, and update the relevant documentation when commands or public APIs change.

Run `npm test` and the builds or browser checks relevant to your change. Include the results in the pull request, along with any checks you could not run. For device operations, list the devices and OS versions you tested. For interface changes, include screenshots when they help demonstrate the result.

To suggest an app for the Awesome List, follow [Contribute an app](https://ipa-hub.giladgd.com/docs/guide/contributing-apps.md). That guide covers the catalog entry, icon attribution, and release-filter validation.

## Commit message guidelines

Consistent commit messages make project history easier to read and provide the input for generated release notes. The repository installs a commit-message hook that runs commitlint.

### Format

Use a type and subject in the header, followed by an optional body and footer. Separate these parts with blank lines:

```text
<type>: <subject>

<body>

<footer>
```

Keep each line at most 100 characters long.

### Type

| Type | Use for |
| --- | --- |
| `feat` | A new feature |
| `fix` | A bug fix |
| `docs` | Documentation changes |
| `style` | Formatting changes that do not change behavior |
| `refactor` | Code changes that neither fix a bug nor add a feature |
| `perf` | Performance improvements |
| `test` | New tests or corrections to existing tests |
| `build` | Build tooling, CI configuration, or dependency changes |
| `chore` | Other changes that do not modify source or tests |

### Subject

- Use the imperative, present tense: `add`, not `added` or `adds`.
- Begin with a lowercase letter.
- Do not end the subject with a period.

### Body

Explain why the change is needed and how it changes the previous behavior. Use the imperative, present tense, as in the subject.

### Footer

Use the footer to reference related issues and explain breaking changes. `Closes: #123` links the change to an issue it resolves.

Start a breaking-change explanation with `BREAKING CHANGE:`. Describe what changes for users and how they can migrate.

### Reverts

Begin a revert with `revert: ` followed by the original commit's header. Include `This reverts commit <hash>.` in the body, replacing `<hash>` with the reverted commit's SHA.

### Examples

A bug fix that closes an issue:

```text
fix: include paired devices available over the network

Closes: #123
```

A new feature:

```text
feat: support selecting devices by name

Allow an exact device name when choosing an installation destination
```

A documentation update:

```text
docs: explain how to set up a development environment
```

A breaking change:

```text
refactor: move installation methods onto IpaHub

BREAKING CHANGE: obtain an IpaHub instance with getIpaHub() before installing apps
```

## Pull request titles

Use the same `<type>: <subject>` format for the pull request title. Describe the final change, link related issues, and include the relevant verification results in the description.