Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
118 lines (84 loc) · 4.99 KB

CONTRIBUTING.md

File metadata and controls

118 lines (84 loc) · 4.99 KB
Raw

Contributing to the Zenoh Datasource Plugin

Signed commits are required

Important

All commits must be signed (GPG, SSH, or S/MIME) to be merged into this repository. Pull requests with unsigned commits will need to be re-committed with signatures before they can be merged.

Prerequisites

  • Node.js (v24 or later)
  • Go (latest stable version)
  • npm (v11.18.0 or later)
  • Docker (for the recommended development workflow, and required to build the backend at all — see below)

The backend links against zenoh-c via cgo, so it can't be cross-compiled the way the old MQTT client could. The Dockerfile (.config/Dockerfile) downloads the correct zenoh-c release and builds the backend inside a container matching the target platform. Building the backend directly on your host (outside Docker) requires manually downloading a zenoh-c "standalone" release for your platform and pointing CGO_CFLAGS/CGO_LDFLAGS at it — see the backend-builder stage in .config/Dockerfile for the exact steps. Building the frontend (npm run build) has no such requirement.

Development Setup

  1. Clone the repository
  2. Install dependencies: 
    npm install
  3. Build and run everything (frontend + native backend) via Docker: 
    npm run server

Development Workflow

The recommended way to develop is with Docker Compose, which builds the frontend and the native Zenoh backend and starts a pre-configured Grafana instance with the plugin baked in:

npm run server

The plugin (frontend bundle and backend binary) is baked into the image at build time, not bind-mounted from the host, since the backend is a cgo binary tied to the container's platform. This means every change — frontend or backend — requires re-running npm run server to rebuild the image before it shows up; there's no live-reload here. npm run dev (webpack watch) and npm run typecheck/lint/test are still useful for a fast frontend inner loop, but you'll need to rebuild the image to see changes running in Grafana.

You'll need a running Zenoh router (zenohd) reachable from the Grafana container to see live data; point the data source's Endpoint setting at it. If the router runs on your host rather than in this compose file, use host.docker.internal instead of localhost in the endpoint.

After making your changes, ensure checks pass:

npm run typecheck  # Check TypeScript types
npm run lint       # Lint the Typescript code
npm run test:ci    # Run tests
npm run spellcheck # Run spellcheck
mage test          # Run Go tests
mage lint          # Lint Go code

If you've added new functionality, please add appropriate tests.

Project Structure

  • src/ - Frontend TypeScript/React code
  • pkg/ - Backend Go code
    • zenoh/ - Zenoh client implementation
    • plugin/ - Grafana plugin implementation
    • protoc/ - Protobuf message definitions and generated code

Running Against a Local Grafana Instance

Most contributors should use npm run server instead. Docker Compose is the recommended development setup — it builds both the frontend and the native Zenoh backend and starts a pre-configured Grafana instance with no manual setup required.

This section is for the specific case where you already have a Grafana installation running (in a container or VM matching the platform you built for) and want to load the locally-built plugin into it. If that does not describe your situation, use npm run server instead.

1. Build the plugin

Build the image and extract the plugin directory from it:

docker build -f .config/Dockerfile -t zenoh-datasource-build .
docker create --name zenoh-datasource-extract zenoh-datasource-build
docker cp zenoh-datasource-extract:/var/lib/grafana/plugins/grafana-zenoh-datasource ./dist
docker rm zenoh-datasource-extract

2. Copy the plugin into Grafana's plugins directory

Copy the resulting dist/ directory into your Grafana instance's plugins directory, e.g. /var/lib/grafana/plugins/grafana-zenoh-datasource.

3. Allow the unsigned plugin in Grafana

Local builds are not signed, so you must explicitly permit the plugin in grafana.ini:

[plugins]
allow_loading_unsigned_plugins = grafana-zenoh-datasource

4. Restart Grafana and verify

Restart the Grafana service, then open the Grafana UI and navigate to Administration → Plugins to confirm the Zenoh datasource appears and is enabled.

Submitting PR

If you are creating a PR, ensure to run npx changeset from your branch. Provide the details accordingly. It will create *.md file inside ./.changeset folder. Later during the release, based on these changesets, package version will be bumped and changelog will be generated.

Releasing & Bumping version

To create a new release, execute npx changeset version. This will update the Changelog and bump the version in package.json file. Commit those changes.