@zeix/ui-element/CONTRIBUTING.md

UIElement - minimal reactive framework based on Web Components

# Contributing to UIElement

Thank you for your interest in contributing to **UIElement**! Your contributions help improve the project and benefit the community. This guide outlines how to get involved.

---

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [How to Contribute](#how-to-contribute)
  - [Reporting Issues](#reporting-issues)
  - [Suggesting Enhancements](#suggesting-enhancements)
  - [Submitting Pull Requests](#submitting-pull-requests)
- [Development Setup](#development-setup)
- [Coding Guidelines](#coding-guidelines)
- [Commit Message Guidelines](#commit-message-guidelines)
- [License](#license)

---

## Code of Conduct

By participating in this project, you agree to abide by our **[Code of Conduct](CODE_OF_CONDUCT.md)**. Please ensure that all interactions remain respectful and constructive.

---

## How to Contribute

### Reporting Issues

If you find a bug or have a feature request:

1. **Search the issue tracker** to check if your issue has already been reported.
2. If not, [open a new issue](https://github.com/zeixcom/ui-element/issues/new) and provide:
   - A clear and descriptive title.
   - Steps to reproduce the issue (if applicable).
   - Expected vs. actual behavior.
   - Screenshots or logs, if relevant.

### Suggesting Enhancements

We welcome feature suggestions! Before submitting a proposal:

1. **Check existing discussions and issues** to see if your idea has been considered before.
2. Provide a **use case** and explain why the feature is needed.
3. If possible, include a rough implementation idea.

### Submitting Pull Requests

We love code contributions! To submit a pull request (PR):

1. **Fork the repository** and clone it locally.
2. Create a **new branch** (`feature/my-new-feature` or `fix/bug-name`).
3. Make your changes, following our [Coding Guidelines](#coding-guidelines).
4. Ensure all tests pass before committing.
5. Write a **clear commit message** (see [Commit Message Guidelines](#commit-message-guidelines)).
6. Push your branch and **open a pull request** with:
   - A brief description of your changes.
   - Any related issue numbers (`Fixes #123`).
   - Screenshots (if UI changes are made).

---

## Development Setup

To set up the project locally:

**Install dependencies:**

```sh
bun install
```

(UIElement uses Bun as its package manager and runtime.)

**Run tests in watch mode:**

```sh
bun run test:watch
```

**Build the project:**

```sh
bun run build
```

**Start a development server for docs:**

```sh
bun run serve:docs
```

---

## Coding Guidelines

To maintain a high-quality codebase, please follow these guidelines:

* Follow the project's existing coding style.
* Avoid unnecessary dependencies.
* Use functional programming principles where applicable.
* Prefer composition over inheritance.
* Make sure to lint your code (`bun run lint`) and all tests pass (`bun run test:watch`).

## Commit Message Guidelines

We use **conventional commits** for clear history and automated changelogs.

**Format:**

```txt
type(scope): short description

[optional longer description]
```

**Examples:**

* `feat(ui): add new LazyLoad component`
* `*fix(scheduler): resolve timing issue on initial load`
* `docs: update documentation for Context API`

**Types:**

* `feat`: New feature
* `fix`: Bug fix
* `docs`: Documentation update
* `style`: Code style changes (no logic changes)
* `refactor`: Code restructuring (no new features or bug fixes)
* `test`: Adding or improving tests
* `chore`: Maintenance tasks (e.g., build system updates)

---

## License

By contributing, you agree that your contributions will be licensed under the MIT License, unless otherwise stated.

---

Thank you for contributing to UIElement! 🚀