From 1648f4b2d66526e193321f076ce0edc7427aa0f3 Mon Sep 17 00:00:00 2001 From: Matej Kubinec Date: Tue, 17 Mar 2026 13:01:49 +0100 Subject: [PATCH 1/2] PMM-7 Update contributing guide for UI development --- CONTRIBUTING.md | 3 + ui/CONTRIBUTING.md | 159 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 162 insertions(+) create mode 100644 ui/CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 971ff51ef5f..d08af35b106 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,6 +30,8 @@ This project is built from several repositories: * [percona/grafana-dashboards](https://github.com/percona/grafana-dashboards) PMM dashboards for database monitoring * [percona/grafana](https://github.com/percona/grafana) user interface for PMM +* [percona/pmm-ui](https://github.com/percona/pmm/tree/v3/ui) native PMM user interface +* [percona/percona-ui](https://github.com/percona/percona-ui) shared Percona user interface component library ### PMM Client @@ -137,6 +139,7 @@ Exporters by themselves are independent applications, so each of them contains i ### UI See [Grafana Dashboards Contribution Guide](https://github.com/percona/grafana-dashboards/blob/main/CONTRIBUTING.md). +See [PMM UI Contribution Guide](https://github.com/percona/pmm/blob/v3/ui/CONTRIBUTING.md). ## Tests diff --git a/ui/CONTRIBUTING.md b/ui/CONTRIBUTING.md new file mode 100644 index 00000000000..2f483029789 --- /dev/null +++ b/ui/CONTRIBUTING.md @@ -0,0 +1,159 @@ +# PMM UI Contribution Guide + +This guide covers contributing to the PMM UI—the native user interface for [Percona Monitoring and Management (PMM)](https://www.percona.com/software/database-tools/percona-monitoring-and-management). For project-wide policies (CLA, Code of Conduct, bug reporting, PR rules, feature builds), see the main [CONTRIBUTING.md](../CONTRIBUTING.md). + +See the main UI entry: [README.md](README.md). + +**Scope:** This guide applies to the `ui/` folder, including `apps/pmm`, `apps/pmm-compat`, and `packages/shared`. + +## Table of contents + +1. [Prerequisites](#prerequisites) +2. [Tech Stack](#tech-stack) +3. [Repository Structure](#repository-structure) +4. [Setup](#setup) +5. [Development Workflow](#development-workflow) +6. [Testing @percona/percona-ui Locally](#testing-perconapercona-ui-locally) +7. [Code Quality](#code-quality) +8. [Submitting Changes](#submitting-changes) + +## Prerequisites + +- [Node 22](https://nodejs.org/en) or later (you can use [nvm](https://github.com/nvm-sh/nvm) to manage Node versions) +- [Yarn](https://yarnpkg.com/) +- For full-stack testing with PMM server: Docker + +## Tech Stack + +The UI uses a monorepo setup with: + +- **Build & package management:** Yarn workspaces, [Turborepo](https://turborepo.com/) +- **Language & framework:** [TypeScript](https://www.typescriptlang.org/), [React](https://react.dev/) +- **Bundling:** [Vite](https://vitejs.dev/) (pmm app), [Webpack](https://webpack.js.org/) (pmm-compat), [Rollup](https://rollupjs.org/) (shared package) +- **Testing:** [Vitest](https://vitest.dev/) (pmm), Jest (pmm-compat, shared) +- **UI:** MUI, [@percona/percona-ui](https://github.com/percona/percona-ui) +- **Code quality:** [Prettier](https://prettier.io/) (@percona/prettier-config), ESLint + +## Repository Structure + +```mermaid +flowchart TB + subgraph apps [Apps] + pmm[PMM - Main UI] + pmmCompat[PMM Compat - Grafana Plugin] + end + subgraph packages [Packages] + shared[Shared - Common Code] + end + pmm --> shared + pmmCompat --> shared +``` + +- **apps/pmm** — Main PMM UI application (Vite, Vitest). See [apps/pmm/README.md](apps/pmm/README.md). +- **apps/pmm-compat** — Grafana application plugin that handles communication between Grafana and the PMM UI via an iframe messaging channel. See [apps/pmm-compat/README.md](apps/pmm-compat/README.md). +- **packages/shared** — Shared code used by both apps. + +## Setup + +From the `ui/` directory: + +```bash +make setup +``` + +Or directly: + +```bash +yarn install +``` + +## Development Workflow + +### Run the UI + +```bash +make dev +``` + +This starts the apps via Turborepo. + +For full integration (UI + PMM server), run `docker compose up` from `ui/` alongside `make dev`. The Vite dev server is proxied through the PMM server (see `pmm-dev.conf`). + +### Commands + +| Command | Description | +| ------------- | ---------------------------- | +| `make dev` | Start development servers | +| `make build` | Build all packages and apps | +| `make lint` | Run ESLint across workspace | +| `make format` | Format with Prettier | +| `make test` | Run all unit tests | +| `make clean` | Remove build artifacts | +| `make ci` | Setup, lint, test, and build | + +## Testing @percona/percona-ui locally + +To test changes to the shared [@percona/percona-ui](https://github.com/percona/percona-ui) library locally: + +1. Clone the percona-ui repository and, from its `lib` folder, run `pnpm build:watch` and `yarn link`. +2. In `ui/apps/pmm`, run `yarn link @percona/percona-ui` and uncomment the `exclude` block in `vite.config.ts`. +3. Any change in percona-ui will trigger a build and refresh in PMM. +4. When done: comment back the `exclude` block, run `yarn unlink @percona/percona-ui` and `yarn install --force` from `ui/apps/pmm`. +5. Restart the dev server between linking and unlinking. + +## Code Quality + +### Linting + +```bash +make lint +``` + +ESLint runs per app and package. The `pmm` app extends the shared package config. + +### Formatting + +```bash +make format +``` + +Prettier formats `**/*.{ts,tsx,md}` across the workspace using `@percona/prettier-config`. + +### Type checking + +```bash +yarn check-types +``` + +Runs TypeScript type checks via Turborepo. + +### Tests + +- **pmm:** Vitest with jsdom and React Testing Library (see `apps/pmm/src/setupTests.ts`). +- **pmm-compat, shared:** Jest. + +Use `testUtils.tsx`, `testWrapper.tsx`, and `testStubs` from `apps/pmm/src/utils/` when writing component tests. + +## Submitting Changes + +Follow the main [CONTRIBUTING.md](../CONTRIBUTING.md) for: + +- Signing the CLA and Code of Conduct +- Branch naming (e.g., `PMM-1234-short-description`) +- Commit message format +- Pull request process and review expectations + +### Before opening a PR + +1. Run `make lint`, `make test`, and `make build` (or `make ci`). +2. Ensure all tests pass and lint rules are satisfied. +3. Add `pmm-review-fe` as reviewer for UI changes. +4. For full integration testing, create a Feature Build as described in the main contribution guide. + +### Related documentation + +- [Working with Git and GitHub](../docs/process/GIT_AND_GITHUB.md) +- [Tech stack](../docs/process/tech_stack.md) +- [Best practices](../docs/process/best_practices.md) + +Note: `best_practices.md` is oriented toward backend (Go). For the UI, follow Prettier and ESLint configs for code style. From 52f1c8a9ba95182203b01067c9e8783aa68d3fbb Mon Sep 17 00:00:00 2001 From: Matej Kubinec Date: Tue, 17 Mar 2026 14:02:03 +0100 Subject: [PATCH 2/2] PMM-7 Update PMM doc link in ui readme --- ui/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ui/README.md b/ui/README.md index e05e1caad10..ce059278359 100644 --- a/ui/README.md +++ b/ui/README.md @@ -7,7 +7,7 @@ PMM helps users to: - Optimize Database Performance - Improve Data Security -See the [PMM Documentation](https://www.percona.com/doc/percona-monitoring-and-management/2.x/index.html) for more information. +See the [PMM Documentation](https://docs.percona.com/percona-monitoring-and-management/index.html) for more information. ## Pre-Requisites