From bf6c5808774581222bb1c608ceb3d743aa5a0157 Mon Sep 17 00:00:00 2001 From: MacRimi Date: Mon, 10 Aug 2026 19:15:01 +0200 Subject: [PATCH] docs: refresh CONTRIBUTING + README for coordination flow + Monitor section --- CONTRIBUTING.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++-- README.md | 3 +- 2 files changed, 99 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 36aedf1a..daa4d78d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,6 +21,7 @@ Thank you for your interest in contributing to **ProxMenux**! This document cove 8. [Variable & Style Conventions](#8-variable--style-conventions) 9. [Do's and Don'ts](#9-dos-and-donts) 10. [Submitting a Contribution](#10-submitting-a-contribution) +11. [Contributing to the Monitor](#11-contributing-to-the-monitor) --- @@ -89,8 +90,10 @@ initialize_cache ## 2. Project Structure +ProxMenux is split into two main trees: the **shell scripts** (menu-driven CLI, covered by this guide) and the **Monitor** (Next.js + Flask web dashboard, covered in [§11](#11-contributing-to-the-monitor)). + ``` -scripts/ +scripts/ # Shell scripts — CLI tree (this guide, sections 1–10) ├── menus/ # Top-level menu scripts (entry points) ├── storage/ # Disk, storage and passthrough scripts ├── share/ # NFS, Samba, local share scripts @@ -102,9 +105,19 @@ scripts/ ├── global/ # Shared helper libraries (sourced by other scripts) ├── utils.sh # Shared utility functions and message helpers └── help_info_menu.sh # Interactive help and command reference + +AppImage/ # Monitor — web dashboard (§11) +├── app/ # Next.js app routes +├── components/ # React components (shadcn + Tailwind) +├── lib/i18n/ # i18n provider + language registry +├── messages// # Per-locale JSON catalogs (Monitor UI strings) +├── scripts/ # Flask backend, health monitor, notification manager +└── scripts/build_appimage.sh # AppImage build script + +lang/.json # Per-locale translation cache — CLI shell strings ``` -Every script sources `utils.sh` to get access to the message functions, spinner, color variables, and translation system. +Every shell script sources `utils.sh` to get access to the message functions, spinner, color variables, and translation system. **Shared helper libraries** (in `scripts/global/`) must be sourced explicitly: @@ -667,7 +680,19 @@ if [[ "$VM_SWITCH_ACTION" == "keep_gpu_disable_onboot" ]]; then # WRONG — di ## 10. Submitting a Contribution -Code is submitted via a standard branch-based GitHub workflow. +Code is submitted via a standard branch-based GitHub workflow. Before touching code, take a minute to signal intent — it makes coordination easier and prevents parallel work on the same thing. + +### Where to look and where to signal + +ProxMenux has three coordination surfaces, each with a clear purpose: + +- **[ProxMenux Roadmap project](https://github.com/users/MacRimi/projects/1)** — the strategic direction. Six pillars (multi-node, workload authoring, multi-user & clustering, operational maturity, domain expansion, and in-flight items) group the work the project is investing in. Cards on the board show what's being worked on right now and by whom. +- **[Issues](https://github.com/MacRimi/ProxMenux/issues)** — bug reports and specific feature requests. Any issue with an assignee is already being worked on by that person. +- **[Discussions → Contributor Coordination](https://github.com/MacRimi/ProxMenux/discussions/categories/contributor-coordination)** — the room where contributors announce they're picking up a piece of work, ask for input before opening a PR, or coordinate around larger changes. The [pinned "How we coordinate work"](https://github.com/MacRimi/ProxMenux/discussions/286) thread is the living guide. + +Rule of thumb: **any contribution likely to take more than an hour is worth a short heads-up in Contributor Coordination** — even one sentence saying you're on it. That way nobody else picks up the same work in parallel. + +For general questions (not bug reports, not coordination), use [Discussions → Q&A](https://github.com/MacRimi/ProxMenux/discussions/categories/q-a). ### Branch model @@ -729,6 +754,74 @@ Your PR will be reviewed against this guide. Once approved, it is merged into `d For security issues, see [SECURITY.md](./SECURITY.md). +### Documentation + +Bug fixes usually don't need doc changes — the release notes cover the visible impact. But when your PR adds a new feature (a script, a Monitor view, an API endpoint, a workflow), you're in the best position to explain what it does — you built it. If you can, adding a page or paragraph to the [docs site](https://proxmenux.com/en/docs/introduction) alongside the code lands the whole thing in one PR. If you'd rather focus on the code, that's fine too — just flag it in the PR description so the docs pass is picked up separately. + +The docs site lives in `/web/` and follows its own conventions — see [`web/CONTRIBUTING-TRANSLATIONS.md`](web/CONTRIBUTING-TRANSLATIONS.md) for structure and the translation flow. + --- -*For questions, open an Issue or reach us at proxmenux@macrimi.pro* +## 11. Contributing to the Monitor + +The Monitor is the web dashboard shipped as a self-contained AppImage. It has a different architecture from the shell scripts, so contributions to that side of the project follow different conventions. The coordination flow ([§10 — Where to look and where to signal](#where-to-look-and-where-to-signal)) is the same. + +### Architecture + +- **Frontend** — Next.js 15 with static export, TypeScript, React, [shadcn/ui](https://ui.shadcn.com/) components on top of Tailwind. Code lives in `AppImage/app/` (routes) and `AppImage/components/`. +- **Backend** — Flask, exposed on port 8008 on the Proxmox host. Route modules live in `AppImage/scripts/flask_*_routes.py`; the main server is `AppImage/scripts/flask_server.py`. Persistence is SQLite (`health_monitor.db`). +- **Packaging** — everything gets bundled into a single `ProxMenux-.AppImage` by `AppImage/scripts/build_appimage.sh` and runs as a systemd service (`proxmenux-monitor.service`). + +### UI conventions + +- **All user-visible strings go through the i18n hook** — never hard-code labels. Use `useT()` when the component only needs the translation function (`const t = useT()`), or `useI18n()` when it also needs the current language / setter (`const { language, setLanguage, t } = useI18n()`). Both are exported from `lib/i18n/provider.tsx`. Missing keys fall back to English at runtime. +- **shadcn components** are the baseline (Card, Badge, Select, Switch, Dialog, etc.). Do not roll custom equivalents when a shadcn one exists. +- **Design tokens** live in Tailwind config; use them (`bg-blue-600`, `border-border`) rather than raw hex values. +- **Dark + light theme** must both work. Use tokens that respond to `data-theme` and `prefers-color-scheme`; don't hard-code palette values. + +### Backend conventions + +- **Authentication** — every mutating route (`POST` / `PUT` / `DELETE`) must be decorated with `@require_auth`. Read-only routes accept any authenticated caller. Never expose an admin endpoint without the decorator. +- **Notifications** — new notification event types are registered in `AppImage/scripts/notification_templates.py` (add to the `TEMPLATES` dict, pick a group, set `default_enabled`). Channel dispatch, filtering, and Quiet Hours handling are already handled by `notification_manager.py`. +- **Health checks** — `AppImage/scripts/health_monitor.py` is the single entry point for background checks. New checks slot into the existing scheduler cadence, respect the per-category thresholds in `settings.healthThresholds`, and emit through the notification manager when they cross a level. + +### Adding a new locale + +1. Add the locale code to `LanguageCode` and to `SUPPORTED_LANGUAGES` in `AppImage/lib/i18n/languages.ts`. +2. Import the JSON in `AppImage/lib/i18n/provider.tsx` and add it to `MESSAGE_CATALOG` (order: EN first, then alphabetical by native name). +3. Add `AppImage/messages//common.json` — copy the structure from `en/common.json` and translate the values. Placeholders like `{vmid}`, `{count}` must stay unchanged. +4. Rebuild the AppImage and verify the language appears in Settings → Interface language. + +For CLI shell strings, the translation cache lives in `lang/.json` — see [§7 (Translation Policy)](#7-translation-policy). + +### Local dev + +The AppImage builds on any Debian/Ubuntu host with Node 20+ and Python 3.11+ installed, but is normally built on a Proxmox host so the packaged Python matches the target runtime: + +```bash +cd /path/to/ProxMenux +bash AppImage/scripts/build_appimage.sh +# → produces AppImage/dist/ProxMenux-.AppImage +``` + +The practical iteration cycle for most changes is: edit code → `build_appimage.sh` → deploy the resulting AppImage to a Proxmox test host → restart `proxmenux-monitor.service` → refresh the browser. Rebuild + deploy takes a few minutes on a normal host. + +For cosmetic UI-only iteration you can run the Next.js dev server directly: + +```bash +cd AppImage +npm install +npm run dev # → http://localhost:3000 +``` + +Note that the dev server has no Flask backend on the same host by default: the app is a static export (`output: 'export'`) with relative `/api/*` calls, so the UI renders but all data endpoints fail unless you set up a proxy to a running Monitor. For anything beyond isolated styling / component work, the full build + deploy cycle above is the honest path. + +### Testing + +- **Python tests** — under `AppImage/scripts/tests/`. Run with `python3 -m unittest discover -s AppImage/scripts/tests`. Add a test file when you add non-trivial backend logic (auth, notifications, background checks). +- **UI smoke test** — deploy the built AppImage to a test host, restart `proxmenux-monitor.service`, and walk through the affected views in the browser. There is no formal e2e suite yet; a real-host smoke pass is expected for any UI change. +- **JSON parse** — after editing any i18n catalog, verify it parses: `python3 -c "import json; json.load(open('AppImage/messages//common.json'))"`. + +--- + +*For general questions use [Discussions → Q&A](https://github.com/MacRimi/ProxMenux/discussions/categories/q-a). For bug reports open an Issue. Direct contact: proxmenux@macrimi.pro* diff --git a/README.md b/README.md index 49023573..dea25ed5 100644 --- a/README.md +++ b/README.md @@ -156,12 +156,13 @@ UI translations ship as pre-built JSON files per language (English, Spanish, Fre ProxMenux is an open, collaborative project — contributions of every shape are very welcome, no matter your background. Every PR, bug report, idea, translation or kind word helps move the project forward. -> 📖 **Before sending code**, please read the [**Contributing Guide**](CONTRIBUTING.md). It covers the project structure, the UI design policy (the two-phase `dialog` / `whiptail` flow), message helpers, translation policy and submission conventions — what reviewers will look for in your PR. +> 📖 **Before sending code**, please read the [**Contributing Guide**](CONTRIBUTING.md) — it explains **where to coordinate**, the project structure, the UI design policy (the two-phase `dialog` / `whiptail` flow), message helpers and submission conventions. **Ways to help:** - 💻 **Code** — fix a bug, polish a script, add a feature. Read the [Contributing Guide](CONTRIBUTING.md) first, then [open a pull request](https://github.com/MacRimi/ProxMenux/pulls). - 🐛 **Bug reports** — found something broken? [Open an issue](https://github.com/MacRimi/ProxMenux/issues/new) with steps to reproduce, and the Monitor logs if relevant (`journalctl -u proxmenux-monitor -n 50`). +- 🗺️ **Follow the direction** — see what's being worked on and where the project is heading on the [Roadmap project board](https://github.com/users/MacRimi/projects/1). Coordination happens in [Contributor Coordination](https://github.com/MacRimi/ProxMenux/discussions/categories/contributor-coordination). - 💡 **Ideas & feedback** — share suggestions in [GitHub Discussions](https://github.com/MacRimi/ProxMenux/discussions). Every idea is welcome. - 🌍 **Translations** — the documentation site already supports English and Spanish; help expand it to more languages following the [translation guide](web/CONTRIBUTING-TRANSLATIONS.md) (one page per PR). - 🧪 **Beta testing** — run the [beta build](#-beta-program) and let us know what you find.