# Contributing to mysa2mqtt

First off, thank you for considering contributing to `mysa2mqtt`! Contributions from the community are essential in
making this project better. Whether you want to report a bug, propose new features, improve documentation or submit code
changes, I welcome your input and assistance. This guide will help you get started with contributing.

## Development Environment

This project uses Node.js and npm for development. Make sure you have Node.js 22.4.0 or higher installed.

### Setting Up Your Development Environment

1. Fork the repository on GitHub
2. Clone your fork locally
3. Navigate to the cloned directory
4. Install dependencies using npm:

```bash
npm install
```

### Project Structure

```
mysa2mqtt/
├── src/                          # Source code
│   ├── commander.d.ts            # Commander type definitions
│   ├── logger.ts                 # Logging utilities
│   ├── main.ts                   # Main application entry point
│   ├── options.ts                # Command line options handling
│   ├── session.ts                # Session management
│   └── thermostat.ts             # Thermostat control logic
├── .github/                      # GitHub configuration
│   ├── workflows/                # GitHub Actions workflows
│   │   └── ci.yml                # Continuous integration workflow
│   ├── CODEOWNERS                # Code ownership definitions
│   ├── FUNDING.yml               # GitHub Sponsors configuration
│   └── dependabot.yml            # Dependabot configuration
├── dist/                         # Built JavaScript files (generated)
├── node_modules/                 # Dependencies (generated)
├── .env.local                    # Local environment variables (not source-controlled)
├── session.json                  # Session data file (not source-controlled)
└── package.json                  # Project configuration and dependencies
```

### Development Workflow

1. Create a new branch for your feature or bug fix
2. Make your changes
3. Run linting checks: `npm run lint` and `npm run style-lint`
4. Build the project: `npm run build`
5. Commit your changes using conventional commit format
6. Push your changes to your fork
7. Create a pull request

### Building

Build the project using [tsup](https://github.com/egoist/tsup):

```bash
npm run build
```

This will generate JavaScript files in the `dist/` directory.

## Submitting Pull Requests

### Conventional Commits

This repository uses [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). This means that each commit
message must follow a specific format. The format is as follows:

```
<type>[optional scope]: <description>
```

The `type` must be one of the following:

| Type       | Description                                                                        |
| ---------- | ---------------------------------------------------------------------------------- |
| `feat`     | A new feature.                                                                     |
| `fix`      | A bug fix.                                                                         |
| `docs`     | Documentation only changes.                                                        |
| `test`     | Changes to tests.                                                                  |
| `perf`     | A code change that improves performance.                                           |
| `refactor` | A code change that neither fixes a bug nor adds a feature.                         |
| `style`    | Changes that do not affect the meaning of the code (white-space, formatting, etc). |
| `chore`    | Regular maintenance tasks and updates.                                             |
| `build`    | Changes that affect the build system or external dependencies.                     |
| `ci`       | Changes to CI configuration files and scripts.                                     |
| `revert`   | Reverting a previous commit.                                                       |

The `scope` is optional and should be used to specify the part of the codebase that the commit affects.

The `description` should be a short, concise summary of the changes made in the commit. The description will appear
as-is in the release notes, so make sure it is clear, informative and not too technical.

For example:

```
feat: Added support for dark mode
```

### Semantic Versioning

This repository uses [semantic versioning](https://semver.org/). This means that each release will be versioned
according to the following rules:

- Increment the major version for breaking changes
- Increment the minor version for new features
- Increment the patch version for bug fixes

Releases are automatically generated by [semantic-release](https://github.com/semantic-release/semantic-release) based
on the commit messages. The version number is determined by the type of commits since the last release.

### Coding Standards

This project adheres to a set of coding standards to ensure consistency and maintainability:

1. **TypeScript**: Write all code in TypeScript with proper type annotations.
2. **Documentation**: Use [TSDoc](https://tsdoc.org/) comments for all public APIs.
3. **Clean Code**: Write clear, self-explanatory code with meaningful variable names.
4. **Error Handling**: Properly handle errors and edge cases.

### Code Style

This repository uses [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) to enforce code style and
formatting. All code must pass both linting checks:

```bash
# Run ESLint
npm run lint

# Run Prettier
npm run style-lint
```

The project is configured with specific rules for:

- Maximum line length
- Indentation (2 spaces)
- Quote style (single quotes)
- Semi-colons (required)
- Trailing commas
- And more

These rules are automatically enforced and cannot be overridden. Please make sure that your code follows these
conventions.

### Pull Request Checklist

Before submitting a pull request, please make sure that:

- Your code follows the coding standards and conventions used in the project
- Your code passes linting checks: `npm run lint`
- Your code passes style checks: `npm run style-lint`
- The documentation has been updated to reflect any changes
- Your commit messages follow the conventional commits format
- The build completes successfully: `npm run build`
- You've verified that your changes work as expected