mysa-js-sdk/CONTRIBUTING.md

Contributing to mysa-js-sdk

First off, thank you for considering contributing to mysa-js-sdk! 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

mysa-js-sdk/
├── src/                          # Source code
│   ├── api/                      # Main API classes and client
│   │   └── events/               # Event type definitions
│   ├── lib/                      # Utility libraries
│   └── types/                    # TypeScript type definitions
│       ├── mqtt/                 # MQTT message types
│       │   ├── in/               # Incoming MQTT message types
│       │   └── out/              # Outgoing MQTT message types
│       └── rest/                 # REST API types
├── example/                      # Example usage
├── dist/                         # Built JavaScript files (generated)
├── docs/                         # Generated API documentation (generated)
└── node_modules/                 # Dependencies (generated)

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.

Documentation

Generate API documentation using TypeDoc:

npm run build:docs

This will generate documentation in the docs/ directory.

Environment Variables

To run the example, you'll need to provide your Mysa credentials. Create a .env file in the project root:

MYSA_USERNAME=your-email@example.com
MYSA_PASSWORD=your-password

Important: Never commit your .env file to the repository!

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