vrr/Pulse
2
0
Fork 0
mirror of https://github.com/rcourtman/Pulse.git synced 2026-05-06 07:57:08 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
Pulse/CONTRIBUTING.md
rcourtman 6eb1a10d9b Refactor: Code cleanup and localStorage consolidation 
This commit includes comprehensive codebase cleanup and refactoring:

## Code Cleanup
- Remove dead TypeScript code (types/monitoring.ts - 194 lines duplicate)
- Remove unused Go functions (GetClusterNodes, MigratePassword, GetClusterHealthInfo)
- Clean up commented-out code blocks across multiple files
- Remove unused TypeScript exports (helpTextClass, private tag color helpers)
- Delete obsolete test files and components

## localStorage Consolidation
- Centralize all storage keys into STORAGE_KEYS constant
- Update 5 files to use centralized keys:
  * utils/apiClient.ts (AUTH, LEGACY_TOKEN)
  * components/Dashboard/Dashboard.tsx (GUEST_METADATA)
  * components/Docker/DockerHosts.tsx (DOCKER_METADATA)
  * App.tsx (PLATFORMS_SEEN)
  * stores/updates.ts (UPDATES)
- Benefits: Single source of truth, prevents typos, better maintainability

## Previous Work Committed
- Docker monitoring improvements and disk metrics
- Security enhancements and setup fixes
- API refactoring and cleanup
- Documentation updates
- Build system improvements

## Testing
- All frontend tests pass (29 tests)
- All Go tests pass (15 packages)
- Production build successful
- Zero breaking changes

Total: 186 files changed, 5825 insertions(+), 11602 deletions(-)
2025-11-04 21:50:46 +00:00

3.9 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, React/TypeScript frontend, and the installer tooling.

Project Overview

  • Backend (cmd/, internal/, pkg/) – Go 1.23+ web server that embeds the built frontend and exposes REST + WebSocket APIs.
  • Frontend (frontend-modern/) – Vite + React 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

./scripts/hot-dev.sh        # Backend on :7656, frontend on :7655
npm run mock:on             # Optional: enable mock data

See docs/development/MOCK_MODE.md for tips on synthetic fixtures.

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

  • Dev server: cd frontend-modern && npm run dev
  • Tests: npm run test
  • Lint: npm run lint
  • Format: npm run format
  • Production build: npm run build (copied into internal/api/frontend-modern via the Makefile).

Use modern React patterns (hooks, function components) and prefer TanStack Query for data fetching. Add Storybook stories or screenshots when introducing new UI-heavy features.

Installers & Scripts

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

Document rollout plans and kill switches in docs/installer-v2-rollout.md and MIGRATION_SCAFFOLDING.md.

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!