Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
67 lines (43 loc) · 2.89 KB

CONTRIBUTING.md

File metadata and controls

67 lines (43 loc) · 2.89 KB
Raw

Contributing to MQTTastic Client KMP

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

Prerequisites

  • JDK 21 — required to build all targets
  • Xcode (macOS only) — required for iOS/macOS targets
  • Chrome — required for wasmJs browser tests

Building

See the Build & Test Commands section in AGENTS.md for the full command reference.

Quick start:

./gradlew build              # Full build (compile + test + check) for all targets
./gradlew allTests           # Run all KMP tests (always use this, not bare `test`)
./gradlew jvmTest            # JVM tests only

Important: Always use allTests instead of test — it's the KMP lifecycle task that covers all source sets.

Before submitting a PR, ensure all checks pass:

./gradlew spotlessApply detektAll allTests apiCheck koverVerify

Code Style

This project uses ktlint (via Spotless) and detekt for formatting and static analysis, plus BCV for API compatibility tracking and Kover for code coverage.

Architecture & Commit Conventions

See AGENTS.md for the full architecture rules, commit format, and scope definitions.

Pull Requests

  1. Fork the repository and create a feature branch from main
  2. Keep commits focused — one logical change per commit
  3. Write tests — every new packet type, property, or protocol feature needs encode/decode round-trip tests
  4. Update documentation — if your change affects the public API or architecture, update AGENTS.md
  5. Ensure CI passes — formatting, linting, and all tests must be green

Reporting Issues

When filing an issue, please include:

  • Library version and Kotlin version
  • Target platform(s) affected
  • Minimal reproduction steps or code snippet
  • Expected vs actual behavior

Releasing

The version is derived from git tags — the tag is the single source of truth. The root build.gradle.kts runs git describe --tags --match 'v*' to resolve the version at build time. On an exact tag (e.g. v0.3.6) the version is 0.3.6; between tags it becomes a -SNAPSHOT. You can override at any time with -PVERSION_NAME=....

To cut a release:

  1. Move the ## [Unreleased] entries in CHANGELOG.md under a new ## [x.y.z] - YYYY-MM-DD heading.
  2. Commit with chore(release): x.y.z and tag: git tag vx.y.z && git push --follow-tags.
  3. The Release workflow will publish to Maven Central, create a GitHub Release, and attach sample artifacts (.apk, .deb, .dmg, .msi, wasmJs web zip) built across a per-OS matrix.

License

By contributing, you agree that your contributions will be licensed under the GNU General Public License v3.0.