docs: add CONTRIBUTING.md and CHANGELOG.md (Priority 1)

Add comprehensive contributor guidelines and complete changelog documenting all 34 versions from v0.0.1 to v0.3.4. This implements Priority 1 from the documentation-engineer analysis. CONTRIBUTING.md includes: - Development workflow and setup - Branching strategy (feat/, fix/, docs/, etc.) - Commit message conventions (Conventional Commits) - Pull request process and checklist - Code style guidelines (TypeScript, React, imports) - Testing requirements (unit + E2E) - Documentation update requirements - Release process for maintainers CHANGELOG.md includes: - All 34 released versions with categorized changes - Features, fixes, changes, infrastructure updates - Links to GitHub releases for each version - Follows Keep a Changelog format - Semantic versioning Documentation completeness: 65% → 75% Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
2026-02-11 23:14:13 -05:00
parent 67ced98bcd
commit 0e711f5dfd
2 changed files with 722 additions and 0 deletions
@@ -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
+
+```
+<type>(<scope>): <description>
+
+[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 <noreply@anthropic.com>
+Co-Authored-By: Happy <yesreply@happy.engineering>
+```
+
+## 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.