Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
207 lines (145 loc) · 4.41 KB

CONTRIBUTING.md

File metadata and controls

207 lines (145 loc) · 4.41 KB

Contributing to SuperOps CLI

Thank you for your interest in contributing to the SuperOps CLI! This document provides guidelines and instructions for contributing.

Code of Conduct

We are committed to providing a welcoming and inclusive environment for all contributors. Please be respectful and professional in all interactions.

Getting Started

Prerequisites

  • Node.js 20.0.0 or higher
  • npm or yarn
  • Git

Setup Development Environment

  1. Fork the repository on GitHub
  2. Clone your fork locally:
git clone https://github.com/YOUR-USERNAME/superops-cli.git
cd superops-cli
  1. Install dependencies:
npm install
  1. Set up environment variables for testing:
export SUPEROPS_API_TOKEN="your-test-token"
export SUPEROPS_SUBDOMAIN="your-test-subdomain"
export SUPEROPS_REGION="us"
  1. Build the project:
npm run build
  1. Link for local testing:
npm link

Development Workflow

Making Changes

  1. Create a new branch for your feature or fix:
git checkout -b feature/your-feature-name
  1. Make your changes following our coding standards
  2. Test your changes thoroughly
  3. Commit your changes with clear, descriptive messages

Coding Standards

  • Follow the existing code style
  • Use TypeScript for all new code
  • Include type definitions for all functions and exports
  • Add JSDoc comments for public APIs
  • Keep functions focused and single-purpose
  • Prioritize readability and maintainability over cleverness

TypeScript Guidelines

  • Enable strict mode
  • Avoid any types when possible
  • Use interfaces for object shapes
  • Export types alongside implementations

Commit Messages

Follow conventional commit format:

  • feat: add new feature
  • fix: resolve bug in XYZ
  • docs: update README
  • refactor: improve code structure
  • test: add tests for XYZ
  • chore: update dependencies

Testing

Run tests before submitting:

npm test

Run type checking:

npm run typecheck

Run linting:

npm run lint

Building

Build the project to ensure it compiles:

npm run build

Pull Request Process

  1. Update the README.md with details of changes if applicable
  2. Update CHANGELOG.md following Keep a Changelog format
  3. Ensure all tests pass and linting is clean
  4. Push your branch to your fork
  5. Submit a Pull Request to the main repository
  6. Wait for review and address any feedback

Pull Request Guidelines

  • Keep PRs focused on a single feature or fix
  • Include a clear description of the changes
  • Reference any related issues
  • Ensure CI/CD checks pass
  • Respond to review comments promptly

Adding New Commands

When adding new commands:

  1. Create a new command file in src/commands/
  2. Follow the existing command structure
  3. Support both JSON and table output formats
  4. Add appropriate options and filters
  5. Include error handling
  6. Update README.md with usage examples
  7. Update CHANGELOG.md

Example command structure:

import { Command } from 'commander';
import { createClient } from '../utils/client.js';
import { output, outputError } from '../utils/output.js';

export const yourCommand = new Command('resource')
  .description('Manage resources');

yourCommand
  .command('list')
  .description('List resources')
  .option('--format <format>', 'Output format (json|table)', 'json')
  .action(async (options) => {
    try {
      const client = createClient();
      const result = await client.resources.list();
      output(result, options.format);
    } catch (error) {
      outputError(error instanceof Error ? error.message : String(error));
      process.exit(1);
    }
  });

Reporting Issues

When reporting issues, please include:

  • Clear description of the problem
  • Steps to reproduce
  • Expected behavior
  • Actual behavior
  • Environment details (OS, Node version, etc.)
  • Relevant logs or error messages

Feature Requests

We welcome feature requests! Please:

  • Check if the feature already exists or is planned
  • Provide a clear use case
  • Explain the expected behavior
  • Consider contributing the implementation

Questions?

If you have questions about contributing, please open an issue with the question label.

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Recognition

Contributors will be recognized in the project. Thank you for helping improve SuperOps CLI!