mirror of
https://github.com/harvester/harvester-ui-extension.git
synced 2026-05-14 15:01:44 +00:00
docs: add AGENTS.md for AI agent guidance (#837)
* feat: add AGENNTS.md Signed-off-by: Andy Lee <andy.lee@suse.com> * refactor: update based on copilot feedback Signed-off-by: Andy Lee <andy.lee@suse.com> * refactor: update AGENTS.md Signed-off-by: Andy Lee <andy.lee@suse.com> * refactor: update based on AI suggestion Signed-off-by: Andy Lee <andy.lee@suse.com> * refactor: based on comments Signed-off-by: Andy Lee <andy.lee@suse.com> * refactor: some files Signed-off-by: Andy Lee <andy.lee@suse.com> * refactor: boundaries.md Signed-off-by: Andy Lee <andy.lee@suse.com> --------- Signed-off-by: Andy Lee <andy.lee@suse.com>
This commit is contained in:
Andy Lee
GitHub
parent
e74428d951
commit
67bb6dfbd5
261
AGENTS.md
Normal file
261
AGENTS.md
Normal file
@ -0,0 +1,261 @@
|
|||||||
|
> This `./AGENTS.md` file is generated by running `yarn agents:generate`.
|
||||||
|
|
||||||
|
|
||||||
|
# Project Overview
|
||||||
|
|
||||||
|
The Harvester UI Extension is a Rancher extension that provides the user interface for Harvester within the Rancher Dashboard.
|
||||||
|
|
||||||
|
```
|
||||||
|
Note: This extension is available starting from Rancher 2.10.0. Ensure your Rancher version is 2.10.0 or later to access Harvester integration.
|
||||||
|
```
|
||||||
|
|
||||||
|
# Personas
|
||||||
|
|
||||||
|
## Software Developer
|
||||||
|
|
||||||
|
You are an expert Senior Software Engineer specializing in Vue.js and TypeScript. You have deep knowledge of Kubernetes and the Rancher ecosystem.
|
||||||
|
- **Focus**: Writing clean, maintainable, and performant code.
|
||||||
|
- **Priorities**: Adhering to the project's code style, ensuring type safety, and following best practices for component design.
|
||||||
|
|
||||||
|
|
||||||
|
# Agents
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
- ✅ **Always:**
|
||||||
|
- Write to `.github`, `docs/`, `pkg/harvester`, `scripts/`.
|
||||||
|
- Make commits in a new branch (for a PR).
|
||||||
|
- Run `yarn lint:fix` before commits.
|
||||||
|
- Use conventional commit format:
|
||||||
|
```
|
||||||
|
<type>:
|
||||||
|
|
||||||
|
<description>
|
||||||
|
```
|
||||||
|
- Follow existing naming conventions (PascalCase for components, camelCase for functions).
|
||||||
|
- After changing a Vue, JS, or TS file, make sure it's automatically formatted with ESLint.
|
||||||
|
- After updating files in `docs/agents.md/`, run `yarn agents:generate` to update root `AGENTS.md`.
|
||||||
|
- ⚠️ **Ask first:**
|
||||||
|
- Adding dependencies
|
||||||
|
- Upgrading dependencies
|
||||||
|
- 🚫 **Never:**
|
||||||
|
- Commit or log secrets, `.env`, `kubeconfig` or any API keys.
|
||||||
|
- Edit `node_modules/`.
|
||||||
|
- Commit directly to `main` (use PRs).
|
||||||
|
- Skip git hooks with `--no-verify` flag.
|
||||||
|
|
||||||
|
## Tools
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
|
- **Node.js**: `>= 24.0.0` (see `.nvmrc` for the pinned version: `24`)
|
||||||
|
- **Package manager**: `yarn` (v1 classic)
|
||||||
|
|
||||||
|
### Common Commands
|
||||||
|
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `yarn install --frozen-lockfile` | Install dependencies (CI-safe, no lockfile changes) |
|
||||||
|
| `RANCHER_ENV=harvester API=https://<harvester-ip> yarn dev` | Start development server at `https://127.0.0.1:8005` |
|
||||||
|
| `yarn build-pkg harvester` | Build the Harvester extension package |
|
||||||
|
| `yarn serve-pkgs` | Serve the locally built extension for testing |
|
||||||
|
| `yarn lint` | Run ESLint (zero warnings allowed) |
|
||||||
|
| `yarn lint:fix` | Run ESLint with auto-fix |
|
||||||
|
| `yarn clean` | Clean build artifacts |
|
||||||
|
| `yarn agents:generate` | Regenerate `AGENTS.md` from `docs/agents.md/` sources |
|
||||||
|
|
||||||
|
### Development
|
||||||
|
|
||||||
|
- **Start dev server**:
|
||||||
|
```bash
|
||||||
|
RANCHER_ENV=harvester API=https://your-harvester-ip yarn dev
|
||||||
|
```
|
||||||
|
- `API` should point to a running Harvester cluster (e.g., `https://x.x.x.x`).
|
||||||
|
- The dashboard will be available at `https://127.0.0.1:8005`.
|
||||||
|
|
||||||
|
### Building
|
||||||
|
|
||||||
|
- **Build extension package**:
|
||||||
|
```bash
|
||||||
|
yarn build-pkg harvester
|
||||||
|
```
|
||||||
|
- **Serve locally built extension** (for integration testing with a Rancher instance):
|
||||||
|
```bash
|
||||||
|
yarn serve-pkgs
|
||||||
|
```
|
||||||
|
|
||||||
|
### Linting
|
||||||
|
|
||||||
|
- **Check** (must pass with zero warnings):
|
||||||
|
```bash
|
||||||
|
yarn lint
|
||||||
|
```
|
||||||
|
- **Auto-fix**:
|
||||||
|
```bash
|
||||||
|
yarn lint:fix
|
||||||
|
```
|
||||||
|
- ESLint covers `.js`, `.ts`, and `.vue` files.
|
||||||
|
- Always run `yarn lint:fix` before committing.
|
||||||
|
|
||||||
|
### Commit Conventions
|
||||||
|
|
||||||
|
- Commits are validated by [commitlint](https://commitlint.js.org/) via a Husky `commit-msg` hook.
|
||||||
|
- Follow [Conventional Commits](https://www.conventionalcommits.org/) format (configured in `commitlint.config.js`).
|
||||||
|
|
||||||
|
### Agent Documentation
|
||||||
|
|
||||||
|
- Source files live in `docs/agents.md/` (agents, contributors, personas subdirectories).
|
||||||
|
- After editing any source file, regenerate the root `AGENTS.md`:
|
||||||
|
```bash
|
||||||
|
yarn agents:generate
|
||||||
|
```
|
||||||
|
|
||||||
|
# Contributors Guide
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
|
Please see the [Harvester UI Extension README](https://github.com/harvester/harvester-ui-extension).
|
||||||
|
|
||||||
|
To get started, follow the `Development Setup` section.
|
||||||
|
|
||||||
|
## Project Information
|
||||||
|
|
||||||
|
- **Tech Stack:**
|
||||||
|
- `Vue.js`: Framework
|
||||||
|
- `Linting`: ESLint
|
||||||
|
- `CSS`: SCSS should be used
|
||||||
|
- `TypeScript`: Primary language for logic.
|
||||||
|
- **Code Style and Standards:**
|
||||||
|
- `Language`: TypeScript is preferred for new code.
|
||||||
|
- `Vue.js`:
|
||||||
|
- Composition API components are preferred over Options API.
|
||||||
|
- Large pages with lots of code and styles should be avoided by breaking the page up into smaller Vue components.
|
||||||
|
- Place source tag above template above style.
|
||||||
|
- style tag should contain `lang='scss' scoped`.
|
||||||
|
- `Linting`: Follow the ESLint configuration in the root.
|
||||||
|
|
||||||
|
- **File Structure:**
|
||||||
|
- `.github/`: CI/CD workflows and Renovate config.
|
||||||
|
- `docs/`: Documentation source for `AGENTS.md` generation.
|
||||||
|
- `scripts/`: Bash scripts for build, CI and doc generation.
|
||||||
|
- `pkg/harvester/`: Main extension source. Files are named after K8s resource types (e.g., `kubevirt.io.virtualmachine`, `harvesterhci.io.volume`).
|
||||||
|
- `index.ts`: Plugin entry point — registers the product and auto-imports models/detail/edit views.
|
||||||
|
- `types.ts`: `HCI` constant mapping 60+ K8s resource types to string identifiers.
|
||||||
|
- `components/`: Reusable Vue components (VNC/serial console, settings panels, upgrade banners, filters).
|
||||||
|
- `config/`: Constants — settings keys, table column definitions, feature flags, type mappings, doc links.
|
||||||
|
- `detail/`: Read-only detail views per resource type. Complex resources use subdirectories with tabs.
|
||||||
|
- `dialog/`: Modal dialogs for operations (VM clone/migrate/restart, backup/restore, device passthrough, etc.).
|
||||||
|
- `edit/`: Create/edit forms. Complex resources (e.g., VM) split into subcomponents (CpuMemory, Network, Volume, CloudConfig, etc.).
|
||||||
|
- `formatters/`: Table cell formatters — state badges, usage bars, resource references.
|
||||||
|
- `l10n/`: Localization (`en-us.yaml`).
|
||||||
|
- `list/`: List (table) views per resource type, mirroring `detail/` and `edit/` naming.
|
||||||
|
- `mixins/`: Shared Vue mixins — VM helpers (`harvester-vm/`) and disk helpers (`harvester-disk.js`).
|
||||||
|
- `models/`: Model classes extending `SteveModel` with computed properties and actions. Base class: `harvester.js`.
|
||||||
|
- `pages/`: Route-level pages — dashboard, support, console, members, brand, alertmanager.
|
||||||
|
- `promptRemove/`: Custom delete-confirmation dialogs (VM, backup).
|
||||||
|
- `routing/`: Vue Router config — all product routes (CRUD, console, support, upgrade, etc.).
|
||||||
|
- `store/`: Vuex modules — `harvester-common.js` for shared state; `harvester-store/` for VM/resource creation actions with Steve integration.
|
||||||
|
- `styles/`: Global SCSS files.
|
||||||
|
- `utils/`: Helpers — VM volume templates, CPU/memory calc, cron parsing, regex validators, feature flags.
|
||||||
|
- `validators/`: Form validation functions per resource type, pushing i18n error messages.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Harvester UI Extension Development Guide
|
||||||
|
|
||||||
|
1. Backward Compatibility
|
||||||
|
The Harvester UI Extension supports earlier cluster versions (e.g., UI Ext v1.8.0 works with clusters v1.7.0 and v1.6.0). It uses Feature Flags defined in pkg/config/feature-flags to ensure the UI matches the cluster's specific version.
|
||||||
|
|
||||||
|
2. Implementation Steps for New Features
|
||||||
|
To add a feature in a new release, follow these steps:
|
||||||
|
|
||||||
|
Register: Add a unique [Feature Name] to the corresponding release array in the configuration.
|
||||||
|
|
||||||
|
Check: Use the following getter to verify if the feature is enabled for the current version:
|
||||||
|
|
||||||
|
```
|
||||||
|
computed: {
|
||||||
|
newFeatureEnabled() {
|
||||||
|
return this.$store.getters['harvester-common/getFeatureEnabled']('[Feature Name]');
|
||||||
|
},
|
||||||
|
},
|
||||||
|
```
|
||||||
|
Render: Use the result of the check to conditionally render the UI components.
|
||||||
|
|
||||||
|
|
||||||
|
## E2E Tests (Cypress)
|
||||||
|
|
||||||
|
See https://github.com/harvester/harvester-ui-tests
|
||||||
|
|
||||||
|
## Node Dependencies
|
||||||
|
|
||||||
|
Dependencies are managed via `package.json` and `yarn`
|
||||||
|
|
||||||
|
- To install dependencies use `yarn install`. This will fail if dependencies and versions listed in `package.json` are out of step with the `yarn.lock` file
|
||||||
|
- To add a dependency use `yarn run add:no-lock ...` instead of `yarn add`
|
||||||
|
- To upgrade a dependency use `yarn run upgrade:no-lock ...` instead of `yarn upgrade`
|
||||||
|
|
||||||
|
|
||||||
|
Renovate automatically updates dependencies and opens upgrade PRs after 10:00 AM on Sundays (`Asia/Taipei`).
|
||||||
|
For the Renovate config, see `.github/renovate.json`.
|
||||||
|
|
||||||
|
|
||||||
|
## Milestone guidance
|
||||||
|
|
||||||
|
- All issues must first be resolved in the `main` branch
|
||||||
|
- If backports are needed they can be made via the backport bot
|
||||||
|
- pull requests
|
||||||
|
- comment `@Mergifyio backport <target branch>` e.g. `@Mergifyio backport release-harvester-v1.8`
|
||||||
|
- All backported pull requests must link to a backported issue
|
||||||
|
|
||||||
|
|
||||||
|
## Creating a branch
|
||||||
|
|
||||||
|
### To resolve an issue
|
||||||
|
- Checkout the branch matching the milestone of the issue `git checkout ${targetMilestoneBranch}`. Replace `${targetMilestoneBranch}` with the target milestone of the issue. For example
|
||||||
|
- `main` for the latest unreleased minor version
|
||||||
|
- `release-harvester-v.X` for release minor versions
|
||||||
|
- `release-harvester-v1.6`
|
||||||
|
- `release-harvester-v1.7`
|
||||||
|
- `release-harvester-v1.8`
|
||||||
|
- Ensure you have the latest of that branch `git pull --rebase`
|
||||||
|
- Checkout the branch to commit the changes to `git checkout issue-${issueNumber}`. Replace `${issueNumber}` with the issue number.
|
||||||
|
|
||||||
|
## Creating a commit
|
||||||
|
|
||||||
|
- This project uses commit-lint with [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to ensure consistent and meaningful commit messages.
|
||||||
|
|
||||||
|
### Commit Message Format
|
||||||
|
All commit messages must follow the conventional commit format:
|
||||||
|
```
|
||||||
|
<type>[optional scope]: <description>
|
||||||
|
|
||||||
|
[optional body]
|
||||||
|
|
||||||
|
[optional footer(s)]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Supported Types
|
||||||
|
- feat: New features
|
||||||
|
- fix: Bug fixes
|
||||||
|
- docs: Documentation changes
|
||||||
|
- style: Code style changes (formatting, missing semicolons, etc.)
|
||||||
|
- refactor: Code refactoring
|
||||||
|
- perf: Performance improvements
|
||||||
|
- test: Adding or updating tests
|
||||||
|
- build: Build system or external dependencies
|
||||||
|
- ci: CI/CD changes
|
||||||
|
- chore: Other changes that don't modify src or test files
|
||||||
|
- revert: Reverts a previous commit
|
||||||
|
- wip: Work in progress
|
||||||
|
- deps: Dependency updates
|
||||||
|
- security: Security fixes
|
||||||
|
|
||||||
|
## Creating a Pull Request
|
||||||
|
|
||||||
|
- Pull requests must come from forks
|
||||||
|
- Description should always have commit supported type prefix. E.g `fix: XXX`, `feat: OOO`
|
||||||
|
- A Pull Request will only be merged once
|
||||||
|
- ALL CI gates have passed
|
||||||
|
- At least one harvester/harvester-ui-extension code owners reviews and approves the PR
|
||||||
|
|
||||||
63
docs/agents.md/README
Normal file
63
docs/agents.md/README
Normal file
@ -0,0 +1,63 @@
|
|||||||
|
# Agents.md
|
||||||
|
|
||||||
|
This folder contains files used to construct a single root `AGENTS.md`
|
||||||
|
|
||||||
|
We do this because
|
||||||
|
- The single commonality between almost all AI tools is that they look for a root `AGENTS.md`
|
||||||
|
- Having the information in a single place for all AI tools is better than duplicating and maintaining the information in multiple files for each AI tool
|
||||||
|
|
||||||
|
## Process
|
||||||
|
1. Add files to or update files in `./docs/agents.md/agents`, `./docs/agents.md/personas`, `./docs/agents.md/contributors`.
|
||||||
|
2. Each file must
|
||||||
|
- Start markdown headers at the `##` level
|
||||||
|
- End in a new line
|
||||||
|
- Order contents in AGENTS.md by giving an optional number prefix
|
||||||
|
3. Run `yarn agents:generate`.
|
||||||
|
- Take the contents of `./docs/agents.md/template_agents.md`
|
||||||
|
- Insert the contents of the agents, personas and contributors files
|
||||||
|
- Output to `./AGENTS.md`
|
||||||
|
4. Commit all changes, including root `./AGENTS.md` and any files that link to it
|
||||||
|
|
||||||
|
## Guidance
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
When referencing code or configuration it's good to include an example
|
||||||
|
|
||||||
|
## Future Tasks
|
||||||
|
- Add real world examples when referencing code
|
||||||
|
- Create a GH workflow to monitor `agents.md` folder files in a PR, if changed run generate script and add new AGENTS.md to PR
|
||||||
|
- Discuss
|
||||||
|
- Three multi AI tool related questions
|
||||||
|
- Questions
|
||||||
|
- how AI specific patterns, like co-pilot instructions, can be expressed in a way to be adopted by or reduce duplication with the root agents.md
|
||||||
|
- how AI tool specific metadata code can be included
|
||||||
|
- multiple agents vs personas approach works
|
||||||
|
- Proposal
|
||||||
|
- Generic information applicable to all AI tools is added to the root `agents.md`
|
||||||
|
- Agent, instruction or other AI specific files or patterns can be used in files specific to that AI tool. They must not contain duplicate information to the root `agents.md`
|
||||||
|
- The root `agents.md` continues to be AI tool agnostic
|
||||||
|
- How can folder specific agents be used
|
||||||
|
- Proposal
|
||||||
|
- `agents.md` are added to folders as long as most LLMs can make use of them and they do not duplicate information in the root `agents.md`
|
||||||
|
|
||||||
|
## Test Prompts
|
||||||
|
|
||||||
|
To validate LLMs are picking up information consider running the following prompts.
|
||||||
|
|
||||||
|
### Information
|
||||||
|
|
||||||
|
Can they provide correct information?
|
||||||
|
|
||||||
|
- `what's this project about?`
|
||||||
|
- `can you tell me the process for fixing a github issue in this repo?`
|
||||||
|
- `what makes a good software developer?`
|
||||||
|
- `what should never be done in this project?`
|
||||||
|
- `what are the folders in this project for?`
|
||||||
|
- `what are the env vars i could use when running e2e tests?`
|
||||||
|
|
||||||
|
### Actions
|
||||||
|
|
||||||
|
Can they use the information in their actions?
|
||||||
|
|
||||||
|
Pending
|
||||||
23
docs/agents.md/agents/boundaries.md
Normal file
23
docs/agents.md/agents/boundaries.md
Normal file
@ -0,0 +1,23 @@
|
|||||||
|
## Boundaries
|
||||||
|
|
||||||
|
- ✅ **Always:**
|
||||||
|
- Write to `.github`, `docs/`, `pkg/harvester`, `scripts/`.
|
||||||
|
- Make commits in a new branch (for a PR).
|
||||||
|
- Run `yarn lint:fix` before commits.
|
||||||
|
- Use conventional commit format:
|
||||||
|
```
|
||||||
|
<type>:
|
||||||
|
|
||||||
|
<description>
|
||||||
|
```
|
||||||
|
- Follow existing naming conventions (PascalCase for components, camelCase for functions).
|
||||||
|
- After changing a Vue, JS, or TS file, make sure it's automatically formatted with ESLint.
|
||||||
|
- After updating files in `docs/agents.md/`, run `yarn agents:generate` to update root `AGENTS.md`.
|
||||||
|
- ⚠️ **Ask first:**
|
||||||
|
- Adding dependencies
|
||||||
|
- Upgrading dependencies
|
||||||
|
- 🚫 **Never:**
|
||||||
|
- Commit or log secrets, `.env`, `kubeconfig` or any API keys.
|
||||||
|
- Edit `node_modules/`.
|
||||||
|
- Commit directly to `main` (use PRs).
|
||||||
|
- Skip git hooks with `--no-verify` flag.
|
||||||
65
docs/agents.md/agents/tools.md
Normal file
65
docs/agents.md/agents/tools.md
Normal file
@ -0,0 +1,65 @@
|
|||||||
|
## Tools
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
|
- **Node.js**: `>= 24.0.0` (see `.nvmrc` for the pinned version: `24`)
|
||||||
|
- **Package manager**: `yarn` (v1 classic)
|
||||||
|
|
||||||
|
### Common Commands
|
||||||
|
|
||||||
|
| Command | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `yarn install --frozen-lockfile` | Install dependencies (CI-safe, no lockfile changes) |
|
||||||
|
| `RANCHER_ENV=harvester API=https://<harvester-ip> yarn dev` | Start development server at `https://127.0.0.1:8005` |
|
||||||
|
| `yarn build-pkg harvester` | Build the Harvester extension package |
|
||||||
|
| `yarn serve-pkgs` | Serve the locally built extension for testing |
|
||||||
|
| `yarn lint` | Run ESLint (zero warnings allowed) |
|
||||||
|
| `yarn lint:fix` | Run ESLint with auto-fix |
|
||||||
|
| `yarn clean` | Clean build artifacts |
|
||||||
|
| `yarn agents:generate` | Regenerate `AGENTS.md` from `docs/agents.md/` sources |
|
||||||
|
|
||||||
|
### Development
|
||||||
|
|
||||||
|
- **Start dev server**:
|
||||||
|
```bash
|
||||||
|
RANCHER_ENV=harvester API=https://your-harvester-ip yarn dev
|
||||||
|
```
|
||||||
|
- `API` should point to a running Harvester cluster (e.g., `https://x.x.x.x`).
|
||||||
|
- The dashboard will be available at `https://127.0.0.1:8005`.
|
||||||
|
|
||||||
|
### Building
|
||||||
|
|
||||||
|
- **Build extension package**:
|
||||||
|
```bash
|
||||||
|
yarn build-pkg harvester
|
||||||
|
```
|
||||||
|
- **Serve locally built extension** (for integration testing with a Rancher instance):
|
||||||
|
```bash
|
||||||
|
yarn serve-pkgs
|
||||||
|
```
|
||||||
|
|
||||||
|
### Linting
|
||||||
|
|
||||||
|
- **Check** (must pass with zero warnings):
|
||||||
|
```bash
|
||||||
|
yarn lint
|
||||||
|
```
|
||||||
|
- **Auto-fix**:
|
||||||
|
```bash
|
||||||
|
yarn lint:fix
|
||||||
|
```
|
||||||
|
- ESLint covers `.js`, `.ts`, and `.vue` files.
|
||||||
|
- Always run `yarn lint:fix` before committing.
|
||||||
|
|
||||||
|
### Commit Conventions
|
||||||
|
|
||||||
|
- Commits are validated by [commitlint](https://commitlint.js.org/) via a Husky `commit-msg` hook.
|
||||||
|
- Follow [Conventional Commits](https://www.conventionalcommits.org/) format (configured in `commitlint.config.js`).
|
||||||
|
|
||||||
|
### Agent Documentation
|
||||||
|
|
||||||
|
- Source files live in `docs/agents.md/` (agents, contributors, personas subdirectories).
|
||||||
|
- After editing any source file, regenerate the root `AGENTS.md`:
|
||||||
|
```bash
|
||||||
|
yarn agents:generate
|
||||||
|
```
|
||||||
70
docs/agents.md/contributors/1_contributors.md
Normal file
70
docs/agents.md/contributors/1_contributors.md
Normal file
@ -0,0 +1,70 @@
|
|||||||
|
## Getting Started
|
||||||
|
|
||||||
|
Please see the [Harvester UI Extension README](https://github.com/harvester/harvester-ui-extension).
|
||||||
|
|
||||||
|
To get started, follow the `Development Setup` section.
|
||||||
|
|
||||||
|
## Project Information
|
||||||
|
|
||||||
|
- **Tech Stack:**
|
||||||
|
- `Vue.js`: Framework
|
||||||
|
- `Linting`: ESLint
|
||||||
|
- `CSS`: SCSS should be used
|
||||||
|
- `TypeScript`: Primary language for logic.
|
||||||
|
- **Code Style and Standards:**
|
||||||
|
- `Language`: TypeScript is preferred for new code.
|
||||||
|
- `Vue.js`:
|
||||||
|
- Composition API components are preferred over Options API.
|
||||||
|
- Large pages with lots of code and styles should be avoided by breaking the page up into smaller Vue components.
|
||||||
|
- Place source tag above template above style.
|
||||||
|
- style tag should contain `lang='scss' scoped`.
|
||||||
|
- `Linting`: Follow the ESLint configuration in the root.
|
||||||
|
|
||||||
|
- **File Structure:**
|
||||||
|
- `.github/`: CI/CD workflows and Renovate config.
|
||||||
|
- `docs/`: Documentation source for `AGENTS.md` generation.
|
||||||
|
- `scripts/`: Bash scripts for build, CI and doc generation.
|
||||||
|
- `pkg/harvester/`: Main extension source. Files are named after K8s resource types (e.g., `kubevirt.io.virtualmachine`, `harvesterhci.io.volume`).
|
||||||
|
- `index.ts`: Plugin entry point — registers the product and auto-imports models/detail/edit views.
|
||||||
|
- `types.ts`: `HCI` constant mapping 60+ K8s resource types to string identifiers.
|
||||||
|
- `components/`: Reusable Vue components (VNC/serial console, settings panels, upgrade banners, filters).
|
||||||
|
- `config/`: Constants — settings keys, table column definitions, feature flags, type mappings, doc links.
|
||||||
|
- `detail/`: Read-only detail views per resource type. Complex resources use subdirectories with tabs.
|
||||||
|
- `dialog/`: Modal dialogs for operations (VM clone/migrate/restart, backup/restore, device passthrough, etc.).
|
||||||
|
- `edit/`: Create/edit forms. Complex resources (e.g., VM) split into subcomponents (CpuMemory, Network, Volume, CloudConfig, etc.).
|
||||||
|
- `formatters/`: Table cell formatters — state badges, usage bars, resource references.
|
||||||
|
- `l10n/`: Localization (`en-us.yaml`).
|
||||||
|
- `list/`: List (table) views per resource type, mirroring `detail/` and `edit/` naming.
|
||||||
|
- `mixins/`: Shared Vue mixins — VM helpers (`harvester-vm/`) and disk helpers (`harvester-disk.js`).
|
||||||
|
- `models/`: Model classes extending `SteveModel` with computed properties and actions. Base class: `harvester.js`.
|
||||||
|
- `pages/`: Route-level pages — dashboard, support, console, members, brand, alertmanager.
|
||||||
|
- `promptRemove/`: Custom delete-confirmation dialogs (VM, backup).
|
||||||
|
- `routing/`: Vue Router config — all product routes (CRUD, console, support, upgrade, etc.).
|
||||||
|
- `store/`: Vuex modules — `harvester-common.js` for shared state; `harvester-store/` for VM/resource creation actions with Steve integration.
|
||||||
|
- `styles/`: Global SCSS files.
|
||||||
|
- `utils/`: Helpers — VM volume templates, CPU/memory calc, cron parsing, regex validators, feature flags.
|
||||||
|
- `validators/`: Form validation functions per resource type, pushing i18n error messages.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Harvester UI Extension Development Guide
|
||||||
|
|
||||||
|
1. Backward Compatibility
|
||||||
|
The Harvester UI Extension supports earlier cluster versions (e.g., UI Ext v1.8.0 works with clusters v1.7.0 and v1.6.0). It uses Feature Flags defined in pkg/config/feature-flags to ensure the UI matches the cluster's specific version.
|
||||||
|
|
||||||
|
2. Implementation Steps for New Features
|
||||||
|
To add a feature in a new release, follow these steps:
|
||||||
|
|
||||||
|
Register: Add a unique [Feature Name] to the corresponding release array in the configuration.
|
||||||
|
|
||||||
|
Check: Use the following getter to verify if the feature is enabled for the current version:
|
||||||
|
|
||||||
|
```
|
||||||
|
computed: {
|
||||||
|
newFeatureEnabled() {
|
||||||
|
return this.$store.getters['harvester-common/getFeatureEnabled']('[Feature Name]');
|
||||||
|
},
|
||||||
|
},
|
||||||
|
```
|
||||||
|
Render: Use the result of the check to conditionally render the UI components.
|
||||||
|
|
||||||
3
docs/agents.md/contributors/2_e2e-tests.md
Normal file
3
docs/agents.md/contributors/2_e2e-tests.md
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
## E2E Tests (Cypress)
|
||||||
|
|
||||||
|
See https://github.com/harvester/harvester-ui-tests
|
||||||
12
docs/agents.md/contributors/node-dependencies.md
Normal file
12
docs/agents.md/contributors/node-dependencies.md
Normal file
@ -0,0 +1,12 @@
|
|||||||
|
## Node Dependencies
|
||||||
|
|
||||||
|
Dependencies are managed via `package.json` and `yarn`
|
||||||
|
|
||||||
|
- To install dependencies use `yarn install`. This will fail if dependencies and versions listed in `package.json` are out of step with the `yarn.lock` file
|
||||||
|
- To add a dependency use `yarn run add:no-lock ...` instead of `yarn add`
|
||||||
|
- To upgrade a dependency use `yarn run upgrade:no-lock ...` instead of `yarn upgrade`
|
||||||
|
|
||||||
|
|
||||||
|
Renovate automatically updates dependencies and opens upgrade PRs after 10:00 AM on Sundays (`Asia/Taipei`).
|
||||||
|
For the Renovate config, see `.github/renovate.json`.
|
||||||
|
|
||||||
58
docs/agents.md/contributors/resolving_gh_issues.md
Normal file
58
docs/agents.md/contributors/resolving_gh_issues.md
Normal file
@ -0,0 +1,58 @@
|
|||||||
|
## Milestone guidance
|
||||||
|
|
||||||
|
- All issues must first be resolved in the `main` branch
|
||||||
|
- If backports are needed they can be made via the backport bot
|
||||||
|
- pull requests
|
||||||
|
- comment `@Mergifyio backport <target branch>` e.g. `@Mergifyio backport release-harvester-v1.8`
|
||||||
|
- All backported pull requests must link to a backported issue
|
||||||
|
|
||||||
|
|
||||||
|
## Creating a branch
|
||||||
|
|
||||||
|
### To resolve an issue
|
||||||
|
- Checkout the branch matching the milestone of the issue `git checkout ${targetMilestoneBranch}`. Replace `${targetMilestoneBranch}` with the target milestone of the issue. For example
|
||||||
|
- `main` for the latest unreleased minor version
|
||||||
|
- `release-harvester-v.X` for release minor versions
|
||||||
|
- `release-harvester-v1.6`
|
||||||
|
- `release-harvester-v1.7`
|
||||||
|
- `release-harvester-v1.8`
|
||||||
|
- Ensure you have the latest of that branch `git pull --rebase`
|
||||||
|
- Checkout the branch to commit the changes to `git checkout issue-${issueNumber}`. Replace `${issueNumber}` with the issue number.
|
||||||
|
|
||||||
|
## Creating a commit
|
||||||
|
|
||||||
|
- This project uses commit-lint with [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to ensure consistent and meaningful commit messages.
|
||||||
|
|
||||||
|
### Commit Message Format
|
||||||
|
All commit messages must follow the conventional commit format:
|
||||||
|
```
|
||||||
|
<type>[optional scope]: <description>
|
||||||
|
|
||||||
|
[optional body]
|
||||||
|
|
||||||
|
[optional footer(s)]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Supported Types
|
||||||
|
- feat: New features
|
||||||
|
- fix: Bug fixes
|
||||||
|
- docs: Documentation changes
|
||||||
|
- style: Code style changes (formatting, missing semicolons, etc.)
|
||||||
|
- refactor: Code refactoring
|
||||||
|
- perf: Performance improvements
|
||||||
|
- test: Adding or updating tests
|
||||||
|
- build: Build system or external dependencies
|
||||||
|
- ci: CI/CD changes
|
||||||
|
- chore: Other changes that don't modify src or test files
|
||||||
|
- revert: Reverts a previous commit
|
||||||
|
- wip: Work in progress
|
||||||
|
- deps: Dependency updates
|
||||||
|
- security: Security fixes
|
||||||
|
|
||||||
|
## Creating a Pull Request
|
||||||
|
|
||||||
|
- Pull requests must come from forks
|
||||||
|
- Description should always have commit supported type prefix. E.g `fix: XXX`, `feat: OOO`
|
||||||
|
- A Pull Request will only be merged once
|
||||||
|
- ALL CI gates have passed
|
||||||
|
- At least one harvester/harvester-ui-extension code owners reviews and approves the PR
|
||||||
5
docs/agents.md/personas/software_developer.md
Normal file
5
docs/agents.md/personas/software_developer.md
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
## Software Developer
|
||||||
|
|
||||||
|
You are an expert Senior Software Engineer specializing in Vue.js and TypeScript. You have deep knowledge of Kubernetes and the Rancher ecosystem.
|
||||||
|
- **Focus**: Writing clean, maintainable, and performant code.
|
||||||
|
- **Priorities**: Adhering to the project's code style, ensuring type safety, and following best practices for component design.
|
||||||
22
docs/agents.md/template_agents.md
Normal file
22
docs/agents.md/template_agents.md
Normal file
@ -0,0 +1,22 @@
|
|||||||
|
> This `./AGENTS.md` file is generated by running `yarn agents:generate`.
|
||||||
|
|
||||||
|
|
||||||
|
# Project Overview
|
||||||
|
|
||||||
|
The Harvester UI Extension is a Rancher extension that provides the user interface for Harvester within the Rancher Dashboard.
|
||||||
|
|
||||||
|
```
|
||||||
|
Note: This extension is available starting from Rancher 2.10.0. Ensure your Rancher version is 2.10.0 or later to access Harvester integration.
|
||||||
|
```
|
||||||
|
|
||||||
|
# Personas
|
||||||
|
|
||||||
|
`<personas>`
|
||||||
|
|
||||||
|
# Agents
|
||||||
|
|
||||||
|
`<agents>`
|
||||||
|
|
||||||
|
# Contributors Guide
|
||||||
|
|
||||||
|
`<contributors>`
|
||||||
@ -49,7 +49,8 @@
|
|||||||
"publish-pkgs": "./node_modules/@rancher/shell/scripts/extension/publish",
|
"publish-pkgs": "./node_modules/@rancher/shell/scripts/extension/publish",
|
||||||
"parse-tag-name": "./node_modules/@rancher/shell/scripts/extension/parse-tag-name",
|
"parse-tag-name": "./node_modules/@rancher/shell/scripts/extension/parse-tag-name",
|
||||||
"commitlint": "commitlint --edit",
|
"commitlint": "commitlint --edit",
|
||||||
"prepare": "husky"
|
"prepare": "husky",
|
||||||
|
"agents:generate": "./scripts/generate-agent-and-persona-mds.sh"
|
||||||
},
|
},
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"@commitlint/load": "^19.8.1",
|
"@commitlint/load": "^19.8.1",
|
||||||
|
|||||||
44
scripts/generate-agent-and-persona-mds.sh
Executable file
44
scripts/generate-agent-and-persona-mds.sh
Executable file
@ -0,0 +1,44 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
set -e
|
||||||
|
|
||||||
|
# Get the directory of the script
|
||||||
|
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
|
||||||
|
# Project root is one level up from scripts/
|
||||||
|
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
|
||||||
|
|
||||||
|
# Source files
|
||||||
|
TEMPLATE_FILE="${PROJECT_ROOT}/docs/agents.md/template_agents.md"
|
||||||
|
AGENTS_DIR="${PROJECT_ROOT}/docs/agents.md/agents"
|
||||||
|
CONTRIBUTORS_DIR="${PROJECT_ROOT}/docs/agents.md/contributors"
|
||||||
|
PERSONAS_DIR="${PROJECT_ROOT}/docs/agents.md/personas"
|
||||||
|
|
||||||
|
# Destination file
|
||||||
|
OUTPUT_FILE="${PROJECT_ROOT}/AGENTS.md"
|
||||||
|
|
||||||
|
insert_directory_contents() {
|
||||||
|
local dir="$1"
|
||||||
|
if [ -d "$dir" ]; then
|
||||||
|
for file in "$dir"/*; do
|
||||||
|
if [ -f "$file" ]; then
|
||||||
|
cat "$file"
|
||||||
|
echo ""
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
echo "Generating ${OUTPUT_FILE}..."
|
||||||
|
|
||||||
|
while IFS= read -r line || [ -n "$line" ]; do
|
||||||
|
if [[ "$line" == *"<agents>"* ]]; then
|
||||||
|
insert_directory_contents "${AGENTS_DIR}"
|
||||||
|
elif [[ "$line" == *"<contributors>"* ]]; then
|
||||||
|
insert_directory_contents "${CONTRIBUTORS_DIR}"
|
||||||
|
elif [[ "$line" == *"<personas>"* ]]; then
|
||||||
|
insert_directory_contents "${PERSONAS_DIR}"
|
||||||
|
else
|
||||||
|
echo "$line"
|
||||||
|
fi
|
||||||
|
done < "${TEMPLATE_FILE}" > "${OUTPUT_FILE}"
|
||||||
|
|
||||||
|
echo "Done."
|
||||||
Loading…
x
Reference in New Issue
Block a user