mysa2mqtt/CONTRIBUTING.md

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:

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:

npm run build

This will generate JavaScript files in the dist/ directory.

Submitting Pull Requests

Conventional Commits

This repository uses conventional commits. 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. 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 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 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 and Prettier to enforce code style and formatting. All code must pass both linting checks:

# 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