diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..5a2024797 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,14 @@ +Thanks for taking the time to prepare a change. + +Before submitting, please note: + +- I am not accepting unsolicited external pull requests for this repository. +- The normal contribution path is to open an issue or discussion first. +- PRs opened without prior maintainer direction may be closed without detailed + review. + +If this PR was opened in error, please close it and open an issue instead: +https://github.com/rcourtman/Pulse/issues + +If this PR was explicitly requested by the maintainer for a tracked issue, +include the issue number and the requested scope below. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f8a1b0240..c65d73976 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,146 +1,72 @@ # 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. +Pulse is maintained as a single-maintainer project. ---- +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. -## Project Overview +## What To Open -- **Backend (`cmd/`, `internal/`, `pkg/`)** – Go 1.23+ 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 + 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. +- Bug reports: use the bug report issue form and include exact reproduction + steps, Pulse version, installation type, and any relevant logs or diagnostics. +- 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](SECURITY.md) instead of opening a public + report for sensitive problems. ---- +## Pull Request Policy -## Getting Started +- 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. +- Keep reproduction steps minimal and exact. +- State the Pulse version and image or package you are actually running. +- Include screenshots, logs, API output, or diagnostics when they clarify the + problem. +- Separate bug reports from feature requests; avoid mixing both into one issue. + +## Local Development Notes + +This repository still contains the development tooling needed to reproduce and +debug problems locally. If you are investigating a bug before opening an issue, +these commands are the main entry points: ```bash git clone https://github.com/rcourtman/Pulse.git cd Pulse -# Install dependencies -brew install go node npm # or use your distro equivalents +brew install go node npm -# Install JS deps cd frontend-modern npm install cd .. ``` -### Hot Reload Dev Loop - -```bash -./scripts/hot-dev.sh # Backend on :7656, frontend on :7655 -npm run mock:on # Optional: enable mock data -``` - -Backend-only hot reload (requires `air`): - -```bash -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 +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` +- Lint: `golangci-lint run ./...` +- Format: `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 +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). +- Production build: `npm run build` -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 `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! +Those notes are here to help with investigation and reproduction. They are not +an invitation to submit external pull requests. diff --git a/README.md b/README.md index 3917764af..02d4805fd 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,10 @@ --- +Issue-first contribution policy: please open an issue or discussion before +investing time in a code change. External pull requests are not part of the +normal contribution flow for this repository. See [CONTRIBUTING.md](CONTRIBUTING.md). + ## 🚀 Overview Pulse is a modern, unified dashboard for monitoring your **infrastructure** across Proxmox, Docker, and Kubernetes. It consolidates metrics, alerts, and AI-powered insights from all your systems into a single, beautiful interface.