mirror of
https://github.com/MacRimi/ProxMenux.git
synced 2026-09-14 10:47:36 +00:00
docs: refresh CONTRIBUTING + README for coordination flow + Monitor section
This commit is contained in:
MacRimi
+97
-4
@@ -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/<lang>/ # Per-locale JSON catalogs (Monitor UI strings)
|
||||
├── scripts/ # Flask backend, health monitor, notification manager
|
||||
└── scripts/build_appimage.sh # AppImage build script
|
||||
|
||||
lang/<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-<version>.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/<lang>/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/<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-<version>.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/<lang>/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*
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user