diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..fa68a71 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,265 @@ +# Changelog + +All notable changes to the Headlamp Polaris Plugin will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.3.4] - 2026-02-12 + +### Fixed +- Removed all `@mui/material` and `@mui/icons-material` imports causing plugin load failure +- Fixed plugin settings page registration (changed name from 'polaris' to 'headlamp-polaris-plugin') +- Added dark mode support using MUI CSS variables for proper theme adaptation +- Resolved TypeScript compilation errors in plugin registration calls + +### Changed +- Replaced all MUI components with standard HTML elements and inline styles +- Updated `registerDetailsViewSection` and `registerAppBarAction` to match Headlamp plugin API v0.13.0 +- App bar badge, settings buttons, and UI elements now use theme-aware CSS variables + +### Infrastructure +- Migrated from Gitea to GitHub Actions exclusively +- Added CI workflow for lint, type-check, build, and test +- Enhanced E2E testing documentation with comprehensive guides +- Added documentation-engineer subagent + +## [0.3.3] - 2026-02-12 + +### Fixed +- Corrected plugin settings registration name to match package.json +- Added displaySaveButton parameter to settings registration + +## [0.3.2] - 2026-02-12 + +### Fixed +- Removed all MUI dependencies to fix plugin loading in Headlamp v0.39.0+ +- Plugin now loads correctly in sidebar and routes + +## [0.3.1] - 2026-02-12 + +### Fixed +- TypeScript compilation errors in `registerDetailsViewSection` and `registerAppBarAction` calls +- Test failures in DashboardView (added missing SimpleTable mock) + +## [0.3.0] - 2026-02-11 + +### Added +- App bar badge displaying cluster Polaris score +- Inline audit sections in resource detail views (Deployment, StatefulSet, DaemonSet, Job, CronJob) +- Exemption management UI (view/add exemptions via annotations) +- Connection testing button in plugin settings +- Top issues dashboard with severity-based filtering +- Namespace drawer navigation with URL hash support + +### Changed +- Migrated namespace detail to right-side drawer panel +- Improved drawer keyboard navigation (Escape to close) +- Enhanced settings page with connection testing + +### Fixed +- Empty namespace crash handling +- Drawer navigation pattern for better UX + +## [0.2.5] - 2025-12-XX + +### Fixed +- Improved theming and settings visibility + +## [0.2.4] - 2025-12-XX + +### Changed +- Increased namespace detail panel width to 1000px for better readability + +## [0.2.3] - 2025-12-XX + +### Added +- Full URL support for custom Polaris dashboards +- Support for external Polaris instances (not just service proxy) + +## [0.2.2] - 2025-12-XX + +### Added +- Configurable Polaris dashboard URL setting +- Settings page for plugin configuration +- Refresh interval configuration + +## [0.2.1] - 2025-12-XX + +### Infrastructure +- Migrated to GitHub as primary repository +- Fixed v0.2.0 checksum in ArtifactHub metadata + +## [0.2.0] - 2025-12-XX + +### Added +- Namespace drawer navigation +- URL hash-based routing for namespaces +- Keyboard shortcuts (Escape to close drawer) + +### Infrastructure +- GitHub release automation +- Improved CI/CD workflow + +## [0.1.7] - 2025-11-XX + +### Documentation +- Removed incorrect development installation instructions + +## [0.1.6] - 2025-11-XX + +### Fixed +- Plugin settings display name changed to "Polaris" + +### Documentation +- Added tooltip to skipped count explaining limitation +- Documented skipped count limitation in README + +## [0.1.5] - 2025-11-XX + +### Fixed +- Restored `:80` port in service proxy URL for correct dashboard access + +## [0.1.4] - 2025-11-XX + +### Added +- Playwright E2E smoke tests +- Test coverage for sidebar, overview, namespaces, and detail views + +### Fixed +- Empty namespace crash (graceful handling) +- Removed `:80` port suffix from service proxy URL for RBAC compatibility + +## [0.1.3] - 2025-11-XX + +### Fixed +- Service proxy URL format for consistent RBAC requirements + +## [0.1.2] - 2025-11-XX + +### Added +- Namespace filtering and sorting +- Enhanced resource table in namespace detail view + +## [0.1.1] - 2025-11-XX + +### Fixed +- Score calculation for resources with mixed results +- Percentage display formatting + +## [0.1.0] - 2025-11-XX + +### Added +- Namespace detail view with resource-level audit results +- Drill-down navigation from namespace list + +### Changed +- Improved data fetching with error handling +- Better loading states + +## [0.0.10] - 2025-11-XX + +### Fixed +- **RBAC Documentation:** Corrected to use `services/proxy` permission instead of ConfigMap access + +### Documentation +- Updated README with accurate RBAC requirements +- Added minimal Role example + +## [0.0.9] - 2025-11-XX + +### Added +- Refresh button for manual data reload +- Last updated timestamp display + +## [0.0.8] - 2025-11-XX + +### Added +- Skipped checks display in check summary +- Improved check categorization (pass/warning/danger/skipped) + +## [0.0.7] - 2025-11-XX + +### Changed +- Enhanced overview dashboard layout +- Better visual hierarchy for cluster score + +## [0.0.6] - 2025-11-XX + +### Added +- Namespace list view with per-namespace scores +- Navigation between overview and namespace views + +## [0.0.5] - 2025-11-XX + +### Fixed +- Data fetching error handling +- API proxy path configuration + +## [0.0.4] - 2025-11-XX + +### Added +- Check distribution visualization +- Pass/Warning/Danger count display + +## [0.0.3] - 2025-11-XX + +### Changed +- Improved cluster score calculation +- Better result aggregation logic + +## [0.0.2] - 2025-11-XX + +### Added +- Cluster score display +- Basic check summary table + +## [0.0.1] - 2025-10-XX + +### Added +- Initial release +- Basic Polaris plugin structure +- Sidebar entry "Polaris" +- Overview page with cluster info +- Data fetching from Polaris dashboard via Kubernetes service proxy +- TypeScript support with strict mode +- React components using Headlamp CommonComponents + +### Infrastructure +- GitHub repository setup +- ArtifactHub package registration +- Automated release workflow +- Basic CI/CD pipeline + +[Unreleased]: https://github.com/cpfarhood/headlamp-polaris-plugin/compare/v0.3.4...HEAD +[0.3.4]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.3.4 +[0.3.3]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.3.3 +[0.3.2]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.3.2 +[0.3.1]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.3.1 +[0.3.0]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.3.0 +[0.2.5]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.2.5 +[0.2.4]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.2.4 +[0.2.3]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.2.3 +[0.2.2]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.2.2 +[0.2.1]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.2.1 +[0.2.0]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.2.0 +[0.1.7]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.1.7 +[0.1.6]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.1.6 +[0.1.5]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.1.5 +[0.1.4]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.1.4 +[0.1.3]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.1.3 +[0.1.2]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.1.2 +[0.1.1]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.1.1 +[0.1.0]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.1.0 +[0.0.10]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.0.10 +[0.0.9]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.0.9 +[0.0.8]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.0.8 +[0.0.7]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.0.7 +[0.0.6]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.0.6 +[0.0.5]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.0.5 +[0.0.4]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.0.4 +[0.0.3]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.0.3 +[0.0.2]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.0.2 +[0.0.1]: https://github.com/cpfarhood/headlamp-polaris-plugin/releases/tag/v0.0.1 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e2ac764 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,457 @@ +# Contributing to Headlamp Polaris Plugin + +Thank you for your interest in contributing to the Headlamp Polaris Plugin! This document provides guidelines and instructions for contributing to the project. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Workflow](#development-workflow) +- [Branching Strategy](#branching-strategy) +- [Commit Message Guidelines](#commit-message-guidelines) +- [Pull Request Process](#pull-request-process) +- [Code Style](#code-style) +- [Testing Requirements](#testing-requirements) +- [Documentation](#documentation) +- [Release Process](#release-process) + +## Code of Conduct + +This project follows a standard code of conduct: +- Be respectful and inclusive +- Welcome newcomers and help them get started +- Focus on constructive feedback +- Assume good intentions + +## Getting Started + +### Prerequisites + +- Node.js 20 or later +- npm or yarn +- Access to a Kubernetes cluster with Headlamp installed (for testing) +- Git + +### Development Setup + +1. **Fork and clone the repository:** + ```bash + git clone https://github.com/YOUR_USERNAME/headlamp-polaris-plugin.git + cd headlamp-polaris-plugin + ``` + +2. **Install dependencies:** + ```bash + npm install + ``` + +3. **Start development mode:** + ```bash + npm start + # Plugin will be available at http://localhost:4466 + ``` + +4. **Run tests:** + ```bash + # Unit tests + npm test + + # E2E tests (requires Headlamp instance) + npm run e2e + ``` + +5. **Build the plugin:** + ```bash + npm run build + ``` + +## Development Workflow + +### Feature Development + +1. Create a feature branch from `main` +2. Make your changes +3. Write/update tests +4. Update documentation +5. Run lint and tests locally +6. Submit a pull request + +### Local Testing + +**Option 1: Development Mode** +```bash +npm start +# Opens Headlamp at http://localhost:4466 with hot reload +``` + +**Option 2: Production Build** +```bash +npm run build +# Plugin bundle created in dist/ +``` + +**Option 3: E2E Testing** +```bash +# Set up environment (see e2e/README.md) +export HEADLAMP_TOKEN=$(kubectl create token headlamp -n kube-system --duration=24h) +npm run e2e +``` + +## Branching Strategy + +### Main Branch + +- **Purpose:** Stable, production-ready code +- **Protection:** Only merge via pull requests +- **Naming:** `main` + +### Feature Branches + +- **Purpose:** Development of new features or fixes +- **Naming Convention:** + - Features: `feat/description` or `feature/description` + - Bug fixes: `fix/description` + - Documentation: `docs/description` + - Refactoring: `refactor/description` + - Chores: `chore/description` + +**Examples:** +```bash +feat/add-exemption-support +fix/dark-mode-theme-colors +docs/update-rbac-guide +refactor/polaris-api-client +chore/upgrade-dependencies +``` + +### Branching Rules + +**✅ ALWAYS use feature branches for:** +- Code changes (new features, bug fixes, refactors) +- Test updates +- CI/CD workflow changes +- Package updates + +**✅ MAY push directly to main for:** +- Documentation-only changes (README.md, CLAUDE.md, comments) +- Version bump commits (`package.json` + `artifacthub-pkg.yml`) + +**❌ NEVER push directly to main for:** +- Any code changes to `src/` +- Test file changes +- Workflow changes +- Dependency updates + +## Commit Message Guidelines + +We follow [Conventional Commits](https://www.conventionalcommits.org/) format: + +### Format + +``` +(): + +[optional body] + +[optional footer(s)] +``` + +### Types + +- **feat:** New feature +- **fix:** Bug fix +- **docs:** Documentation only +- **style:** Code style (formatting, no logic change) +- **refactor:** Code change that neither fixes a bug nor adds a feature +- **perf:** Performance improvement +- **test:** Adding or updating tests +- **chore:** Maintenance tasks (deps, build, CI) +- **ci:** CI/CD changes + +### Scope (Optional) + +- `api` - API-related changes +- `ui` - UI component changes +- `settings` - Plugin settings +- `tests` - Test-related changes +- `docs` - Documentation changes + +### Examples + +```bash +feat(api): add support for custom Polaris dashboard URLs + +fix(ui): resolve dark mode theme color inconsistencies + +docs: update RBAC examples with NetworkPolicy + +chore: bump version to 0.3.5 + +test(e2e): add tests for plugin settings page +``` + +### Footer + +Add `Co-Authored-By` for pair programming or AI assistance: + +``` +feat: add namespace filtering to overview + +Co-Authored-By: Claude Sonnet 4.5 +Co-Authored-By: Happy +``` + +## Pull Request Process + +### Before Creating a PR + +1. **Run all checks locally:** + ```bash + npm run build # Verify build succeeds + npm run lint # Check for linting errors + npm run tsc # Type-check TypeScript + npm test # Run unit tests + npm run format # Format code with Prettier + ``` + +2. **Update documentation:** + - Update README.md if you added features or changed behavior + - Update CLAUDE.md if you changed architecture or constraints + - Add/update JSDoc comments for new APIs + +3. **Write/update tests:** + - Add unit tests for new functions/components + - Update E2E tests if UI behavior changed + - Ensure all tests pass + +### Creating a PR + +1. **Push your branch:** + ```bash + git push origin feat/your-feature + ``` + +2. **Create PR on GitHub:** + - Use a descriptive title following commit conventions + - Fill out the PR template (if available) + - Link related issues with `Fixes #123` or `Closes #456` + +3. **PR Title Format:** + ``` + feat: add exemption management UI + fix: correct score calculation for skipped checks + docs: improve deployment guide with Helm examples + ``` + +4. **PR Description Should Include:** + - Summary of changes + - Motivation and context + - Testing performed + - Screenshots (for UI changes) + - Breaking changes (if any) + +### PR Review Process + +1. **Automated Checks:** + - ✅ CI workflow (lint, type-check, build, test) + - ✅ E2E tests (may fail if plugin not deployed) + +2. **Maintainer Review:** + - Code quality and style + - Test coverage + - Documentation completeness + - Breaking changes assessment + +3. **Merging:** + - Use **merge commits** (not squash, not rebase) + - Delete feature branch after merge + - Maintainers will handle version bumps and releases + +## Code Style + +### TypeScript + +- **Strictness:** Full TypeScript strict mode enabled +- **No `any`:** Use specific types or `unknown` +- **Interfaces over types:** Prefer `interface` for object shapes +- **Named exports:** Use named exports, not default exports + +### React + +- **Functional components:** Use function components with hooks +- **Props interfaces:** Always define props as interfaces +- **Headlamp components:** Use CommonComponents from Headlamp, never raw MUI +- **No inline styles:** Use theme-aware CSS variables + +### Linting and Formatting + +```bash +# Auto-fix linting issues +npm run lint:fix + +# Format code +npm run format + +# Check formatting +npm run format:check +``` + +### Import Organization + +Imports are automatically sorted by eslint. Order: +1. React imports +2. Third-party libraries +3. Headlamp plugin imports +4. Local imports (components, API, types) + +Example: +```typescript +import React from 'react'; +import { SectionBox, StatusLabel } from '@kinvolk/headlamp-plugin/lib/CommonComponents'; +import { usePolarisDataContext } from '../api/PolarisDataContext'; +import { computeScore } from '../api/polaris'; +``` + +### Naming Conventions + +- **Components:** PascalCase (`DashboardView`, `PolarisSettings`) +- **Files:** Match component name (`DashboardView.tsx`) +- **Hooks:** Prefix with `use` (`usePolarisData`) +- **Utilities:** camelCase (`countResults`, `computeScore`) +- **Constants:** UPPER_SNAKE_CASE (`DASHBOARD_URL_DEFAULT`) + +## Testing Requirements + +### Unit Tests (Required) + +- All new functions must have unit tests +- All bug fixes should include regression tests +- Aim for meaningful coverage, not just numbers +- Use descriptive test names + +Example: +```typescript +describe('countResults', () => { + it('counts passing, warning, and danger results correctly', () => { + // Test implementation + }); + + it('includes skipped checks in total count', () => { + // Test implementation + }); +}); +``` + +### E2E Tests (Recommended) + +- Add E2E tests for new UI features +- Update existing tests if behavior changes +- See `e2e/README.md` for detailed instructions + +### Running Tests + +```bash +# Run all unit tests +npm test + +# Run tests in watch mode +npm run test:watch + +# Run E2E tests +npm run e2e + +# Run E2E tests in headed mode (see browser) +npm run e2e:headed +``` + +## Documentation + +### Documentation Updates Required + +When making changes, update relevant documentation: + +#### Code Changes +- **README.md:** User-facing features, installation, configuration +- **CLAUDE.md:** Architecture, constraints, MCP integrations +- **JSDoc:** All public APIs, components, hooks + +#### Test Changes +- **e2e/README.md:** New test scenarios or setup changes + +#### Build/CI Changes +- **README.md:** Build commands, release process +- **.github/workflows/*.yaml:** Workflow comments + +### JSDoc Style + +Use JSDoc for all exported functions, components, and types: + +```typescript +/** + * Counts passing, warning, danger, and skipped Polaris check results. + * + * Skipped checks are identified by severity "ignore" with success false. + * + * @param data - AuditData from Polaris dashboard API + * @returns ResultCounts with totals by status (pass/warning/danger/skipped) + */ +export function countResults(data: AuditData): ResultCounts { + // Implementation +} +``` + +## Release Process + +### Version Numbering + +We follow [Semantic Versioning](https://semver.org/): +- **Major (1.0.0):** Breaking changes +- **Minor (0.1.0):** New features, backward compatible +- **Patch (0.0.1):** Bug fixes, backward compatible + +### Creating a Release + +**Maintainers only:** + +1. **Merge feature PRs to main** + +2. **Bump version:** + ```bash + # Edit package.json and artifacthub-pkg.yml + # Update version and archive-url + git add package.json artifacthub-pkg.yml + git commit -m "chore: bump version to X.Y.Z" + git push origin main + ``` + +3. **Create and push tag:** + ```bash + git tag vX.Y.Z + git push origin vX.Y.Z + ``` + +4. **GitHub Actions automatically:** + - Builds plugin tarball + - Creates GitHub release + - Uploads tarball to release + - Updates `artifacthub-pkg.yml` with checksum + +5. **ArtifactHub syncs within 30 minutes** + +### Pre-release Versions + +For testing before stable release: +- Use `-dev.N` suffix: `v0.3.5-dev.1` +- Follow same process as stable releases +- Mark as "pre-release" on GitHub + +## Getting Help + +- **Questions:** Open a [GitHub Discussion](https://github.com/cpfarhood/headlamp-polaris-plugin/discussions) +- **Bugs:** Open a [GitHub Issue](https://github.com/cpfarhood/headlamp-polaris-plugin/issues) +- **E2E Testing:** See [e2e/README.md](e2e/README.md) +- **Architecture:** See [CLAUDE.md](CLAUDE.md) + +## License + +By contributing, you agree that your contributions will be licensed under the MIT License.