Skip to content

contributing.md

Latest commit

 

History

History
312 lines (220 loc) · 7.36 KB

contributing.md

File metadata and controls

312 lines (220 loc) · 7.36 KB
Raw

Contributing to modbus2mqtt

Thank you for your interest in contributing to modbus2mqtt! This guide will help you get started.

Table of Contents

Code of Conduct

Please be respectful and constructive in all interactions with the community.

Language policy

All changes (code comments, documentation, commit messages, pull request titles and descriptions) must be written in English.

Why

Keeping contributions in English ensures that the widest possible audience can review, maintain, and use the repository.

How this is enforced

  • A workflow runs on pull requests and pushes that scans commit messages and pull request title/body for non-English indicators (for example German umlauts or common German words).
  • If the workflow detects potential non-English text, it will comment on the pull request with guidance and/or fail the check for pushes.

If your native language is not English

  • Use simple clear English. It's fine if the language isn't perfect — clarity is more important than grammar.
  • If you need help translating a short message, open an issue or ask in the project's discussion.

Notes for maintainers

  • The enforcement workflow aims to catch obvious cases (German words and umlauts). It may produce false positives; use judgement when responding.
  • The workflow can be adjusted to whitelist project-specific words or to change sensitivity.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR-USERNAME/modbus2mqtt.git
cd server
  3. Add the upstream repository: 
    git remote add upstream https://github.com/modbus2mqtt/modbus2mqtt.git

Development Setup

For detailed development setup instructions, see the Development Guide.

Quick start:

npm install
npm run install-hooks
npm run build.dev

Development Workflow

1. Create a Feature Branch

git checkout -b feature/my-new-feature

Branch naming conventions:

  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation updates
  • test/ - Test additions or fixes
  • refactor/ - Code refactoring

2. Make Your Changes

Follow the coding standards below.

3. Test Your Changes

# Run unit tests
npm test

# Run specific test file
npm test __tests__/modbus2mqtt/bus_test.tsx

# Run E2E tests
npm run e2e:start
npm run cypress:open

4. Commit Your Changes

Commits are automatically formatted by the pre-commit hook.

git add .
git commit -m "feat: add new feature description"

Commit message format:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • test: - Test changes
  • refactor: - Code refactoring
  • chore: - Maintenance tasks

5. Push to Your Fork

git push origin feature/my-new-feature

6. Open a Pull Request

  1. Go to the original repository on GitHub
  2. Click "New Pull Request"
  3. Select your branch
  4. Fill in the PR template with:
    • Description of changes
    • Related issue numbers
    • Testing performed
    • Screenshots (if UI changes)

Coding Standards

TypeScript

  • Use TypeScript for all new code
  • Enable strict type checking
  • Document public APIs with JSDoc comments

Code Style

  • Code is automatically formatted with Prettier on commit
  • Run manually: npm run prettier
  • Configuration: .prettierrc

Linting

  • ESLint is configured for the project
  • Run: npm run lint (if configured)
  • Fix automatically: npm run lint -- --fix

Naming Conventions

  • Files: Use kebab-case for files: modbus-cache.ts
  • Classes: Use PascalCase: ModbusCache
  • Functions/Variables: Use camelCase: getSpecification
  • Constants: Use UPPER_SNAKE_CASE: MAX_RETRIES
  • Interfaces: Prefix with I: IModbusSpecification

Project Structure

src/
├── server/           # Backend server code
├── server.shared/    # Shared types for server
├── specification/    # Specification handling
├── specification.shared/ # Shared specification types
└── angular/          # Frontend Angular code

__tests__/           # Test files
├── server/          # Server tests
└── specification/   # Specification tests

Testing

Unit Tests (Jest)

Write tests for all new features and bug fixes:

import { expect, it, describe } from '@jest/globals'

describe('MyFeature', () => {
  it('should do something', () => {
    // Arrange
    const input = 'test'

    // Act
    const result = myFunction(input)

    // Assert
    expect(result).toBe('expected')
  })
})

E2E Tests (Cypress)

Add E2E tests for UI changes:

describe('My Feature', () => {
  it('should interact correctly', () => {
    cy.visit('/my-feature')
    cy.get('[data-testid="my-button"]').click()
    cy.contains('Expected Result')
  })
})

Test Coverage

Aim for:

  • Unit test coverage > 80%
  • All critical paths tested
  • Edge cases covered

Submitting Changes

Pull Request Checklist

Before submitting:

  • Code builds without errors: npm run build
  • All tests pass: npm test
  • Code is formatted: npm run prettier
  • Commit messages follow convention
  • Documentation updated (if needed)
  • Changelog updated (for significant changes)

Review Process

  1. Automated checks run on your PR
  2. Maintainers review your code
  3. Address review feedback
  4. Once approved, your PR will be merged

After Merge

  1. Delete your feature branch:

    git branch -d feature/my-new-feature
git push origin --delete feature/my-new-feature

  2. Update your local main branch:

    git checkout main
git pull upstream main

Contributing Specifications

Specifications define how to communicate with Modbus devices.

Create a New Specification

  1. Use the Web UI: http://localhost:3000
  2. Navigate to "Specifications" → "Create New"
  3. Fill in device details:
    • Name and manufacturer
    • Modbus registers
    • Data types and conversions
    • MQTT topics

Test Your Specification

  1. Add test data in the specification
  2. Connect to a real device (if available)
  3. Verify all entities read correctly
  4. Document any quirks or special requirements

Submit Your Specification

  1. Export the specification from the UI
  2. Create a PR with:
    • Specification YAML file
    • Documentation (README in specifications/ folder)
    • Images or datasheets (if available)
    • Test results

Specification Guidelines

  • Use clear, descriptive names
  • Include manufacturer and model information
  • Document all entities thoroughly
  • Add identification rules when possible
  • Include links to official documentation

Getting Help

Recognition

Contributors will be acknowledged in:

  • CREDITS.md file
  • Release notes
  • Project documentation

Thank you for contributing to modbus2mqtt! 🎉