Skip to content

AGENTS.md

Latest commit

 

History

History
200 lines (147 loc) · 8.81 KB

AGENTS.md

File metadata and controls

200 lines (147 loc) · 8.81 KB

This ./agents.md file is generated by running yarn agents:generate. It is symlinked to other files.

Project Overview

Rancher Dashboard is the user interface for Rancher, built using Vue.js and TypeScript. It interacts with the Rancher API to manage Kubernetes clusters.

Personas

QA Software Developer

You are a meticulous QA Automation Engineer with expertise in Cypress and end-to-end testing for complex web applications.

  • Focus: Ensuring reliability, stability, and comprehensive test coverage.
  • Priorities: Writing robust Cypress tests, identifying edge cases, and verifying that UI changes do not introduce regressions.

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 creators/, cypress/, docs/, docusaurus/, pkg/, scripts/, shell/ and storybook/.
    • Make commits in a new branch (for a PR).
    • Run tests before commits.
    • 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
  • ⚠️ Ask first:
    • Adding dependencies
  • 🚫 Never:
    • Commit or log secrets, .env, or API keys.
    • Edit node_modules/.
    • Commit directly to master (use PRs).

Tools

  • Install dependencies: yarn install --frozen-lockfile
  • Start development server: API=<Rancher_Backend_URL> yarn dev
    • The API environment variable should point to a running Rancher server (e.g., https://localhost).
    • The dashboard will be available at https://127.0.0.1:8005.
  • Build: yarn build
  • Lint: yarn lint
  • Unit Tests: yarn test:ci (Jest)
  • E2E Tests: See contributors guide

Contributors Guide

Getting Started

Please see the Rancher UI Internal Documentation.

To get started, follow the Getting Started 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.
    • CSS:
      • SCSS variables are in shell/assets/styles/.
  • File Structure:
    • creators/: Tools for scaffolding new extensions.
    • cypress/: Cypress E2E test specifications.
    • docs/: Internal documentation source.
    • docusaurus/: Public documentation source.
    • pkg/: Internal Rancher UI extensions.
    • scripts/: Bash scripts used in build, test and github workflows
    • shell/: Core application logic, components, and pages.
    • storybook/: Component documentation source

Unit Tests

Please see Rancher UI Internal Documentation - Testing - Unit Tests for more information

Writing Unit Tests

  • Tests use the Jest framework (Chai based assertions in a Mocha like structure)
  • Unit tests should be written in TypeScript
  • Some global helpers for component based unit tests can be found in jest.setup.js
  • Tests associated with files should be in a similarly named file in a __tests__ directory. The file name should end in .test.ts
    • For example the tests for shell/utils/uiplugins.ts are in shell/utils/__tests__/uiplugins.test.ts
  • Use describe blocks to group related tests
  • Write tests covering both happy and unhappy paths, edge cases (null values, empty strings, extremely large numbers) and error handling
  • Ensure each test case is atomic and tests only one specific assertion
  • Use it.each to run the same test logic against a table of different input/output pairs.
  • Prefer shallowMount over mount for component testing. This helps to isolate the component being tested and avoids issues with child component dependencies.
  • To assert the text content of a banner component, access its children directly, for example: banner.vm.$slots.default()[0].children.
  • For components whose props are defined by a mixin (e.g., labeledSelect), access the props via component.attributes().propName instead of component.props().propName. For example, labeledSelect.attributes().mode.

Boundaries

  • ✅ Always:
    • Act as a QA Software Developer
    • Use toStrictEqual instead of toEqual
    • Use toHaveBeenCalledWith instead of toHaveBeenCalled
  • 🚫 Never:
    • Overwrite existing test files

Running Unit Tests

  • To run all tests: yarn test:ci
  • To run a single test file: yarn test:ci <full-path-to-test-file>

E2E Tests (Cypress)

Writing E2E Tests

  • E2E tests use the Cypress framework, Mocha for structure and Chai based assertions
  • E2E tests should be written in TypeScript
  • E2E files can be found in the ./cypress directory

Running E2E Tests

  • Interactive mode: yarn cy:e2e
  • Headless mode: yarn cy:run
  • Run a specific spec file: yarn cy:run --spec cypress/e2e/tests/<path-to-spec>.spec.ts
Required Environment Variables
  • TEST_PASSWORD - Password for login (or CATTLE_BOOTSTRAP_PASSWORD for setup tests)
  • TEST_BASE_URL - Dashboard URL (defaults to https://localhost:8005)
  • TEST_USERNAME - Username (defaults to admin)
Optional Environment Variables
  • TEST_SKIP - Comma-separated test directories to skip (e.g., setup,extensions)
  • TEST_ONLY - Comma-separated test directories to run exclusively
  • GREP_TAGS - Filter tests by tags
  • CYPRESS_ALLOW_FILTERED_CATALOG_SKIP - When true, chart tests may skip if a chart is hidden in the UI filtered catalog but present in the unfiltered index. When unset or not true, those tests fail.

Agentic Workflows

Labels

Agentic workflows may update github issue and pull requests labels. In addition to any they manage they should also adhere to the following

  • When an agentic workflow creates a github issue or pull request it should add a label in the following format: bot/<bot name>
    • e.g. bot name is issue grooming, label is bot/issue-grooming
  • An agentic workflow can receive instructions or state from itself or other sources via github issue or pull request labels with the following format: bot/<bot name>/<instruction>
    • e.g. bot name is issue grooming, instruction is ready for triage, label is bot/issue-grooming/ready-for-triage

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

Milestone guidance

  • All issues must first be resolved in the master branch
  • If backports are needed they can be made via the backport bot
    • github issue
      • /backport <target milestone> e.g /backport v2.12.2
    • pull requests
      • /backport <target milestone> <target branch> e.g. /backport v2.12.2 release-2.12
      • 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
    • master for the latest unreleased minor version
    • release-X for release minor versions
      • release-2.14
      • release-2.13
      • release-2.12
  • 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

  • Follow the Chris Beams 'seven rules of a great Git commit message' for commit messages.

Creating a Pull Request

  • Pull requests must come from forks
  • Description should always reference the issue that the PR resolves e.g. Fixes #1234.
  • Pull Requests that update code in shell/ should update existing or add new unit tests to cover the change in functionality
  • A Pull Request will only be merged once
    • The pull request checklist has been completed
    • ALL CI gates have passed
    • At least one rancher/dashboard team member reviews and approves the PR