Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
103 lines (65 loc) · 5.7 KB

CONTRIBUTING.md

File metadata and controls

103 lines (65 loc) · 5.7 KB

Contributing to KubeStellar Console

Issues Are Welcome

The best way to contribute is by opening an issue. Bug reports, feature requests, UX feedback, and questions all help shape the project.

The fastest way to file an issue or feature request is by navigating to /issue in your running console (requires GitHub OAuth). You can also use GitHub Issues directly. Programmatic issue creation from the console additionally requires FEEDBACK_GITHUB_TOKEN in .env — see README.md for setup.

How Development Works

Most code in this repo is written by coding agents — Claude Opus 4.5/4.6, Gemini, and Codex. PRs are generated, reviewed, and iterated on by these agents with human oversight.

Manual coding PRs are discouraged. They take significantly longer to complete and review compared to agent-generated code. PRs that miss required patterns (isDemoData wiring, useCardLoadingState, locale strings, marketplace vs console) will be sent back — these are things coding agents catch automatically.

All PRs — human or AI — must pass the same 9 hard CI gates before merge. There is no separate path for AI-generated code. See docs/AI-QUALITY-ASSURANCE.md for the full list of quality gates, post-build safety checks, and our regression response model.

If you want to contribute code, use one of the supported agents:

  • Claude Code (Claude Opus 4.5 or 4.6) — strongly recommended. Knows the full codebase, all CLAUDE.md rules, isDemoData wiring, card loading state patterns, and locale requirements. Install: npm install -g @anthropic-ai/claude-code
  • GitHub Copilot — used for automated PR fixes
  • Google Gemini — supported for code generation
  • OpenAI Codex — supported for code generation

New CNCF Project Cards

New monitoring cards for CNCF projects (Karmada, Falco, KEDA, etc.) belong in kubestellar/console-marketplace, not in this repo. The marketplace loads cards on-demand so they don't bloat the core bundle for users who don't need them.

PRs that add new card components to web/src/components/cards/ will be redirected to console-marketplace.

Test PRs Are Favored

The most valuable code contributions are tests — Playwright E2E tests, unit tests, or integration tests submitted as PRs. Tests shape how automated code generation works by defining expected behavior. A failing test PR is more useful than a code PR, because it tells the agents exactly what to build.

See the scripts/ directory for 30+ existing test scripts (API contract, security, helm lint, consistency, card registry integrity, and more). Run any of them directly:

bash scripts/api-contract-test.sh
bash scripts/consistency-test.sh
cd web && npx playwright test --grep "your-test"

Getting Started Locally

Prerequisites: Go 1.25+, Node.js 20+

macOS / Linux:

git clone https://github.com/kubestellar/console.git
cd console
./start-dev.sh

Windows (WSL2):

Native Windows is not supported. Install WSL2 with Ubuntu and run everything from the WSL shell:

# In PowerShell — one-time setup
wsl --install -d Ubuntu

Then from inside the Ubuntu/WSL shell:

sudo apt-get update && sudo apt-get install -y curl git
git clone https://github.com/kubestellar/console.git
cd console
./start-dev.sh

See the Windows (WSL2) section in README.md for additional details on curl gotchas and building from source.

Starts backend on :8080 and frontend on :5174 with a mock dev-user account. See CLAUDE.md for development conventions and card development rules.

Commit Conventions

  • Sign all commits with DCO: git commit -s

Change Tiers

Every PR gets automatically labeled with exactly one tier/* label when it opens. The tier classifies how much review scrutiny the change needs based on which files it touches. Rules live in .github/tier-classifier-rules.yml; logic runs in .github/workflows/tier-classifier.yml.

Label Meaning What it covers
tier/0-automatic Safe — safe to fast-track Lockfiles, go.sum, docs-only, *.md, i18n files, snapshots, generated artifacts
tier/1-lightweight Single-concern, low risk Test-only changes, editor config (.editorconfig, .prettierrc, etc.)
tier/2-standard Default — standard review Everything not matched by another tier
tier/3-restricted Touches security-sensitive paths CODEOWNERS, .github/workflows/**, pkg/auth/**, pkg/api/middleware/**, docs/security/**, Helm RBAC templates, GoReleaser config

Classification rules. A PR is tier 3 if any of its files match a tier-3 path. Otherwise it's tier 0 only if every file is a tier-0 match; tier 1 only if every file is a tier-0 or tier-1 match; otherwise tier 2.

Today: labels are informational. Reviewers can use them to prioritize their queue.

Future (separate PR): tier/0-automatic PRs with CI green will auto-merge via admin squash. Rolling out after a week of label-only observation to confirm the rules don't produce false positives.

This system is adapted from fullsend-ai/fullsend's tier-based change classification — see SECURITY-AI.md for the broader context.

Getting Help