mirror of
https://github.com/bourquep/mysa2mqtt.git
synced 2025-10-21 15:08:07 +00:00
b7a80cb072
* Renamed environment variables * Moved MqttSettings to main.tsx * Using Commander for CLI arguments * PinoLogger * Option for json log format * Updated mysa-js-sdk to latest version * Moved options to their own module * Extracted session file management to the session module * Added deviceId meta to thermostat instance logger * Display version from package.json; added copyright * Create README.md * Build with tsup * Update .gitignore * Remove prepublishOnly npm script * Distributed CLI executable is now working * Update README.md * Dockerfile * Minify the build output * Update README.md * Create initial Github workflow * Create release.config.mjs * Read package version at run-time, not build-time * Update README.md * Create CONTRIBUTING.md * WIP: docker CI job * Trying multiple tags * Enable docker build cache * Testing the docker build cache * Dockerfile: set npm version in final stage for better caching * Testing docker build cache * Moved VERSION arg to the final build stage * Finalized the `docker` build job * Added copyright header to all source files * Specify radix when parsing integer options
161 lines
6.4 KiB
Markdown
161 lines
6.4 KiB
Markdown
# 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
|