development.md

Development Guide: odh-cli

This is the main entry point for odh-cli development documentation. Use this guide to navigate to specific topics.

For architectural information and design decisions, see design.md.

Quick Start

New to the project? Start here:

1. Setup and Build - Build commands, test commands, and development environment setup
2. Coding Conventions - Core coding standards and practices
3. Testing Guidelines - How to write and organize tests
4. Quality Verification - Running linters, tests, and quality checks

Documentation Structure

Getting Started

• setup.md - Build commands, test commands, prohibited commands

Coding Standards

The coding/ directory contains focused coding guidelines:

• coding/conventions.md - Core coding conventions

  • Error handling
  • Function signatures
  • Package organization
  • Naming conventions
  • Code comments (WHY not WHAT)
  • Message constants
  • Command interface pattern

• coding/patterns.md - Architectural patterns and design practices

  • Functional options pattern
  • IOStreams wrapper
  • JQ-based field access
  • Centralized GVK/GVR definitions
  • High-level resource operations
  • Cluster-wide operations

• coding/formatting.md - Code formatting rules

  • Using make fmt
  • Blank imports for auto-registration
  • Import ordering

Testing

• testing.md - Testing practices and conventions
  • Test framework (Gomega)
  • Test data organization
  • Mock organization
  • Struct assertions
  • Kubernetes sets for deduplication
  • Generic type conversion

Extensibility

• extensibility.md - Adding features and extending the CLI
  • Adding new commands
  • Command-specific logic
  • Adding output formats
  • Using the table renderer

Quality and Review

• quality.md - Continuous quality verification

  • Development workflow
  • Lint-fix-first approach
  • Quality gates
  • When to run checks

• code-review.md - Code review guidelines

  • Linter rules and configuration
  • Git commit conventions
  • Task-based commits
  • Pull request checklist
  • Code style summary

Command-Specific Documentation

• lint/architecture.md - Lint command architecture and design
• lint/writing-checks.md - Writing diagnostic checks for the lint command

Common Tasks

Setting Up Development Environment

See setup.md

Writing a New Command

See extensibility.md

Writing Tests

See testing.md

Running Quality Checks

See quality.md

Preparing a Pull Request

See code-review.md

Architecture Documentation

For broader architectural context:

• design.md - Overall CLI design and architecture
• lint/architecture.md - Lint command-specific architecture

Contributing

Before contributing:

1. Read coding/conventions.md and coding/patterns.md
2. Understand testing.md practices
3. Follow the quality.md workflow
4. Review code-review.md guidelines