vrr/Pulse
2
0
Fork 0
mirror of https://github.com/rcourtman/Pulse.git synced 2026-10-03 04:38:48 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 17
Pulse/CONTRIBUTING.md
pulse-triage[bot] 6a77d1b007 Align contributor bug guidance with safe incident intake 
The contributor guide still demanded reproduction steps and a running image even when an install never started or another attempt could cause an outage. Match the current issue forms: accept the original sequence, attempted release, installer provenance and only safely collected redacted evidence.

Contract-Neutral: Contributor reporting guidance only; no installation, release, or runtime contract change.
Change-source: pulse-maintainer
2026-09-29 19:43:18 +01:00

8.6 KiB
Raw Blame History

Contributing to Pulse

Pulse is a single-maintainer project developed with extensive automation, including coding agents. See Development and Automation Transparency for the standing disclosure, authority boundaries, and accountability model.

I am not accepting unsolicited external pull requests for this repository. If you have found a bug, want to propose a feature, or have a concrete improvement idea, please open an issue instead.

This document also keeps the local development notes needed to reproduce, debug, and validate issues across the Go backend, SolidJS/TypeScript frontend, and installer tooling.

What To Open

  • Bug reports: use the bug report issue form and describe the original sequence, the version on the affected running instance (or the version or release asset attempted if installation never completed), the installation type, and any relevant, safely collected evidence. A second reproduction is not required.
  • Feature requests: open an issue describing the problem you want solved, the workflow you are trying to improve, and any constraints that matter.
  • Questions and support requests: use GitHub Discussions when you need help, troubleshooting, or general guidance rather than a tracked defect.
  • Security issues: follow SECURITY.md instead of opening a public report for sensitive problems.

Pull Request Policy

  • External pull requests are not part of the normal contribution flow for this repository.
  • Unsolicited pull requests may be closed without detailed review, even when the underlying idea is valid.
  • If I want code help on a specific issue, I will explicitly ask for it there.
  • Opening an issue first is the right path; it lets me confirm whether the change fits the product direction before anyone spends time building a patch.

How To Make An Issue Useful

  • Search existing issues before opening a new one.
  • Describe what happened before the failure. Do not repeat an action just to produce steps if it could cause data loss, an outage, duplicate changes, or excessive notifications; say why you have not repeated it instead.
  • State the version on the affected running instance. If Pulse never started, give the attempted version or release asset (or say "unknown") and identify the installer or helper when known. Include an image tag or digest only for a running container, not for a bare-metal or LXC install.
  • Include screenshots, redacted logs, API output, or diagnostics when they clarify the problem. If Pulse is running and it is safe to collect, use Settings -> Diagnostics -> Export for GitHub (sanitized) for connection or data failures. Never paste credentials, tokens, private keys, or a command line containing them into an issue.
  • Lead with one primary bug or operator outcome. If the context also exposes another actionable topic, put it in the issue form's dedicated field. Triage will preserve it with a linked disposition; you do not need to refile text you already supplied. See Issue Triage and Topic Integrity.

Project Overview

  • Backend (cmd/, internal/, pkg/) – Go 1.26 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 Go 1.26 and Node.js 24 with your preferred package manager.

# Install the repository and frontend dependencies exactly from their locks
npm ci
npm --prefix frontend-modern ci

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. The managed dev runtime login defaults to admin / adminadminadmin unless you override it with HOT_DEV_AUTH_USER and HOT_DEV_AUTH_PASS.

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 --prefix frontend-modern test
  • Type check: npm --prefix frontend-modern run type-check
  • Lint: npm --prefix frontend-modern run lint
  • Format check: npm --prefix frontend-modern run format:check

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 python3 scripts/check_public_docs.py before submitting public documentation updates. It verifies local links and rejects retired navigation claims on the current documentation surface.

Testing Expectations

  • Every requested PR should note the tests run (go test, frontend tests, or scripts/tests/run.sh, as applicable).
  • 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 Requested Changes

For maintainer-requested code help on a tracked issue:

  1. Link the issue where the maintainer requested the patch.
  2. Fork + branch (git checkout -b feature/my-change).
  3. Make your edits and run relevant tests.
  4. Update docs and changelog entries as needed.
  5. 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.