vrr/Pulse
2
0
Fork 0
mirror of https://github.com/rcourtman/Pulse.git synced 2026-04-28 03:20:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
Pulse/CONTRIBUTING.md
rcourtman 9d74c943c7 Expand managed dev browser proof pack
2026-03-24 21:48:34 +00:00

5.2 KiB
Raw Blame History

Contributing to Pulse

Thanks for investing time in Pulse! This document collects the essentials you need to be productive across the Go backend, SolidJS/TypeScript frontend, and the installer tooling.

Project Overview

  • Backend (cmd/, internal/, pkg/) – Go 1.25+ web server that embeds the built frontend and exposes REST + WebSocket APIs.
  • Architecture (ARCHITECTURE.md) – High-level system design diagrams and explanations.
  • Frontend (frontend-modern/) – Vite + SolidJS app built with TypeScript.
  • Agents (cmd/pulse-*-agent) – Go binaries distributed alongside Pulse for host and Docker telemetry.
  • Documentation (docs/) – Markdown-based guides published to users and referenced from the README.
  • Scripts (scripts/) – Bash installers and helpers bundled for curl-based distribution.

Getting Started

git clone https://github.com/rcourtman/Pulse.git
cd Pulse

# Install dependencies
brew install go node npm # or use your distro equivalents

# Install JS deps
cd frontend-modern
npm install
cd ..

Hot Reload Dev Loop

npm run dev                 # Frontend shell on :5173, backend on :7655
npm run mock:on             # Optional: enable mock data

Use http://127.0.0.1:5173 in the browser for local frontend development. The frontend dev shell proxies /api and /ws to the backend on :7655; do not switch your browser to :7655 unless you are debugging the backend directly.

Backend-only hot reload (requires air):

air -c .air.toml

Set HOT_DEV_USE_PRO=true to build the Pro variant when available.

Mock mode is supported for development, but the internal developer notes are not shipped in this repository.

Backend Workflow

  • Build: go build ./cmd/pulse
  • Tests: go test ./...
  • Lint: golangci-lint run ./... (install via go install if missing)
  • Formatting: gofmt -w ./cmd ./internal ./pkg

Key entry points:

  • HTTP router lives in internal/api.
  • Monitoring engines live under internal/monitor.
  • Configuration parsing resides in internal/config.

When adding new API endpoints, document them in docs/API.md and provide examples where possible.

Frontend Workflow

  • Managed dev runtime: npm run dev
  • Runtime status: npm run dev:status
  • Runtime logs: npm run dev:logs
  • Managed restart: npm run dev:restart
  • Managed backend restart: npm run dev:backend-restart
  • Browser proof pack: npm run dev:verify
  • Foreground managed launcher: npm run dev:foreground
  • Frontend-only escape hatch: cd frontend-modern && npm run dev:frontend-only
  • Tests: npm run test
  • Lint: npm run lint
  • Format: npm run format

The same managed runtime wrappers are available from frontend-modern/ if you start there by habit, so npm run dev, npm run dev:status, and npm run dev:verify behave the same way from either workspace.

  • Production build: npm run build (syncs the Go embed copy in internal/api/frontend-modern/dist automatically).

Use SolidJS patterns (signals, memos, createEffect) and the shared design-system components in components/shared/. Add screenshots when introducing new UI-heavy features.

Design-system lint rules are enforced as CI blockers. Avoid hardcoded structural light/dark classes and broken utility chains; use semantic tokens from frontend-modern/DESIGN_SYSTEM.md.

Installers & Scripts

  • Centralised guidance: docs/internal/SCRIPT_LIBRARY.md
  • Bundling: make bundle-scripts
  • Tests: scripts/tests/run.sh plus integration suites under scripts/tests/integration/

Document rollout plans and kill switches in MIGRATION_SCAFFOLDING.md so future contributors know how to disable risky changes.

Documentation Standards

  • Author or update guides in docs/ when behaviour changes.
  • Organise new topics through docs/README.md so they appear in the docs index.
  • Avoid marketing copy in technical docs—save that for README.md or external sites.
  • Keep instructions evergreen; put release-specific notes in docs/RELEASE_NOTES.md.

Run a quick link check (npm run lint-docs if available, or markdownlint) before submitting large doc updates.

Testing Expectations

  • Every PR should note the tests run (go test, npm test, scripts/tests/run.sh).
  • Add regression coverage when fixing bugs.
  • Mention manual verification steps (e.g., “Proxmox LXC installer tested on PVE 8.1”) if automated coverage is not feasible.

Coding Guidelines

  • Adhere to existing formatting tools (gofmt, prettier, eslint).
  • Name Go packages with short, meaningful identifiers (avoid util).
  • Keep functions focused; prefer small helpers over large monoliths.
  • Prefer context-aware logging (logger.Named("component")) in new Go code.
  • Ensure secrets never reach logs and redact sensitive fields in API responses.

Submitting Changes

  1. Fork + branch (git checkout -b feature/my-change).
  2. Make your edits and run relevant tests.
  3. Update docs and changelog entries as needed.
  4. Open a PR describing:
    • What changed
    • Why it changed
    • Testing performed
    • Rollout / migration concerns

Reviewers will focus on correctness, security, and upgrade paths, so call out anything unusual up front. Thanks again for contributing!