Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
144 lines (97 loc) · 5.41 KB

CONTRIBUTING.md

File metadata and controls

144 lines (97 loc) · 5.41 KB
Raw

Contributing to nmstate-console-plugin

Contributions are welcome. This document covers coding standards, testing, and the pull request process.

For initial setup (clone, install, running the dev server), see README.md.

Coding Standards

TypeScript & React

  • Functional components only, typed with FC from React
  • Use PatternFly 6 components for all UI — no custom HTML elements for standard patterns
  • One component per file — utility files, types (aside from props), constants, etc. go in a utils/ folder within the component's directory
  • Define props as TypeScript type in the same file or a co-located types.ts
  • Default export for page-level components
  • Use path aliases for cross-directory imports: @utils/*, @models, @images/*

Internationalization

All user-visible strings must be translated. Use useNMStateTranslation() for simple strings and the Trans component for strings with embedded HTML:

import { useNMStateTranslation } from '@utils/hooks/useNMStateTranslation';

const MyComponent: FC = () => {
  const { t } = useNMStateTranslation();
  return <p>{t('My translatable string')}</p>;
};

Never hardcode English text in JSX. Run npm run i18n to extract new translation keys.

Linting & Formatting

The project uses ESLint + Prettier with enforced import sorting:

npm run lint          # Check for lint errors
npm run lint:fix      # Auto-fix lint errors

Key rules:

  • Prettier: single quotes, trailing commas, 100-char print width
  • Import sorting: enforced via simple-import-sort — React first, then external packages, then internal paths, then relative imports, then CSS
  • No unused variables: @typescript-eslint/no-unused-vars is set to error
  • No prop-types: disabled (TypeScript types are used instead)

Adding a new view

  1. Create a directory under src/views/{view-name}/
  2. Add a manifest.ts exporting {View}ExposedModules and {View}Extensions
  3. Register the extensions in plugin-manifest.ts
  4. Add a K8s model in src/console-models/ if needed
  5. Export the model from src/console-models/index.ts

Adding a K8s resource model

Create a new file in src/console-models/ following the existing pattern:

import { K8sModel } from '@openshift-console/dynamic-plugin-sdk';

const MyResourceModel: K8sModel = {
  apiGroup: 'nmstate.io',
  apiVersion: 'v1',
  kind: 'MyResource',
  plural: 'myresources',
  // ... other fields
};

export default MyResourceModel;

Export it from src/console-models/index.ts and use @models to import.

Testing

Unit tests (Jest)

npm test                    # Run all tests
npm run test:coverage       # Run with coverage report
npm run test:updateSnapshot # Update snapshots

Tests live alongside source files as *.test.ts(x) or *.spec.ts(x). The SDK and i18n are mocked via src/__mocks__/.

E2E tests (Cypress)

npm run cypress          # Headless Chrome
npm run cypress:open     # Interactive mode

E2E specs live in cypress/e2e/. Tests run against http://localhost:9000 by default (override with BRIDGE_BASE_ADDRESS).

What to test

  • New components: at minimum, test that they render without errors
  • Utility functions: test edge cases and expected transformations
  • E2E: cover user-facing workflows for new views or significant UI changes

Pull Request Process

Commit messages

Follow the existing commit style — short imperative subject line describing the change. Reference the Jira/Bugzilla ID when applicable (e.g., CNV-12345: add physical networks page).

Before submitting

  1. Run npm run lint and fix any errors
  2. Run npm test and ensure tests pass
  3. Test your changes in the console (run npm run start-console)
  4. Update translations if you added user-visible strings (npm run i18n)
  5. Update context files (CLAUDE.md, AGENTS.md, ARCHITECTURE.md) if adding or modifying the directory structure

Review

  • PRs require approval from at least one person in the reviewer list and a different person from the approver list in OWNERS. If the submitter is in one of the lists, their ack is added automatically
  • Merge via merge commit (the repo uses merge commits, not squash)
  • CI runs Prow-based checks — ensure test-prow-e2e.sh passes

CVE and dependency remediation

CVE fixes are the most common PR type. The typical workflow:

  1. Identify the vulnerable transitive dependency (e.g., lodash, immutable, qs) from an OCPBUGS-* ticket
  2. Update or pin the dependency in package.json and regenerate package-lock.json
  3. Create the fix on main, then cherry-pick to every active release branch (currently release-4.17 through release-4.23)
  4. Title format: OCPBUGS-{id}: CVE remediation for {package} on main, prefixed with [release-X.Y] on release branches

Each release branch gets its own PR. Use openshift-cherrypick-robot labels or create cherry-picks manually.

Release branches

The repo maintains multiple active release branches (release-4.17, release-4.18, ..., release-4.23). Each branch tracks a specific OpenShift release:

  • main — development branch for the next release
  • release-X.Y — stable branch for OpenShift X.Y; receives bug fixes and CVE remediations via cherry-picks
  • SDK version must correspond to the target release branch (e.g., release-4.22 uses SDK 4.22.x)

License

This project is licensed under the Apache License 2.0.