mirror of
https://github.com/bourquep/mysa2mqtt.git
synced 2025-10-21 15:08:07 +00:00
build: Build and publish a proper CLI tool with options, also packaged as a Docker image (#2)
* 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
This commit is contained in:
Pascal Bourque
160
CONTRIBUTING.md
Normal file
160
CONTRIBUTING.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user