mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-07-09 16:00:59 +00:00
Document issue-first contribution policy
Pulse is a single-maintainer project and does not accept unsolicited external pull requests. README, CONTRIBUTING, and a new PULL_REQUEST_TEMPLATE now state this directly so contributors hit the policy before investing time in code, and so PRs opened in error point to issues and discussions as the correct intake. CONTRIBUTING is rewritten end-to-end around the new policy: how to file bugs, feature requests, support questions, and security reports; where to look for context (README, ARCHITECTURE, docs/); and the maintainer-direction carve-out for PRs explicitly requested against tracked issues.
This commit is contained in:
rcourtman
parent
3d3b1a9642
commit
84d6aa7ba8
3 changed files with 62 additions and 118 deletions
14
.github/PULL_REQUEST_TEMPLATE.md
vendored
Normal file
14
.github/PULL_REQUEST_TEMPLATE.md
vendored
Normal file
|
|
@ -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.
|
||||
162
CONTRIBUTING.md
162
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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue