Skip to content

Contributing Guide

Thank you for your interest in contributing to the Energy Manager IoT library! This guide will help you get started with the development process.

Development Setup

Prerequisites

Make sure you have the following installed:

  • Node.js (version 14.0 or higher)
  • npm or yarn
  • Git

Setting Up the Development Environment

  1. Fork the repository on GitHub.

  2. Clone your fork locally: 

    git clone https://github.com/jonhvmp/energy-manager-iot.git
cd energy-manager-iot

  3. Install dependencies: 

    npm install

  4. Set up the MQTT broker for testing:

  5. For development purposes, we recommend using Mosquitto
  6. See the Getting Started Guide for installation instructions

Development Workflow

Branch Strategy

  • main - Production-ready code
  • develop - Integration branch for new features
  • Feature branches - Use for developing new features or fixing bugs

Creating a Feature Branch

When starting work on a new feature or bugfix:

git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

Building the Project

To build the TypeScript code:

npm run build

The compiled JavaScript will be output to the dist folder.

Running Examples

You can run the provided examples to test your changes:

npm run example:basic
npm run example:group
npm run example:simulator

Running Tests

The project includes both unit tests and integration tests:

# Run unit tests
npm test

# Run tests in watch mode during development
npm run test:watch

# Run integration tests (requires MQTT broker)
npm run test:integration

Integration Tests

Integration tests require a running MQTT broker. By default, they expect a broker at localhost:1883.

For Windows: 

npm run test:integration:windows

For Linux/MacOS: 

npm run test:integration

Code Style and Linting

Before submitting your code, make sure it follows our coding standards:

# Run linter
npm run lint

# Format code
npm run format

Pull Request Process

  1. Update the documentation to reflect any changes you've made.

  2. Add or update tests as necessary.

  3. Ensure all tests pass and the code builds without errors.

  4. Update the README.md with details of any interface changes.

  5. Submit a pull request to the develop branch.

  6. The PR should include:

  7. A clear title and description
  8. Reference to any relevant issues
  9. List of changes made
  10. Any special considerations or notes for reviewers

Code Style Guidelines

TypeScript Conventions

  • Use TypeScript's strict mode
  • Provide detailed type annotations for public APIs
  • Use interfaces for public-facing types
  • Document complex code sections with comments
  • Use async/await over direct Promise handling
  • Follow the TypeScript Style Guide

Documentation Guidelines

  • Document all public methods, classes, and interfaces
  • Include examples for non-trivial functionality
  • Keep examples simple and focused
  • Use JSDoc comments for code documentation
  • Use Markdown for general documentation

Example of proper JSDoc comments:

/**
 * Sends a command to a specific device
 *
 * @param deviceId - ID of the destination device
 * @param command - Type of command to send
 * @param payload - Optional data to include with the command
 * @returns Promise that resolves when the command is sent
 * @throws {EnergyManagerError} If device not found or not connected to MQTT
 *
 * @example
 * ```ts
 * await manager.sendCommand('sensor01', CommandType.SET_REPORTING, { interval: 60 });
 * ```
 */
public async sendCommand(deviceId: string, command: CommandType, payload?: any): Promise<void> {
  // Implementation
}

Reporting Issues

When reporting issues, please include:

  1. A clear, descriptive title
  2. A detailed description of the issue
  3. Steps to reproduce the behavior
  4. Expected behavior
  5. Actual behavior
  6. Environment information:
  7. Library version
  8. Node.js version
  9. Operating system
  10. MQTT broker used
  11. Any relevant code snippets or logs

Feature Requests

When suggesting features:

  1. Clearly describe the problem the feature would solve
  2. Provide an example of how the feature would be used
  3. Discuss potential implementation approaches if possible
  4. Consider backward compatibility

Code of Conduct

Our Standards

  • Use welcoming and inclusive language
  • Be respectful of differing viewpoints and experiences
  • Focus on what is best for the community and project
  • Show empathy towards other community members

Enforcement

Violations of the code of conduct may result in: - Correction or removal of comments - Temporary or permanent bans from contribution - Removal of submitted content

License

By contributing to Energy Manager IoT, you agree that your contributions will be licensed under the project's license.

Contact

If you have questions about contributing, please contact Jonh Alex Paz de Lima or open an issue on GitHub.