Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
224 lines (170 loc) · 4.77 KB

CONTRIBUTING.md

File metadata and controls

224 lines (170 loc) · 4.77 KB

Contributing to IT Glue CLI

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

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.

Getting Started

Prerequisites

  • Node.js >= 20.0.0
  • npm or yarn
  • Git
  • IT Glue API key for testing

Development Setup

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR-USERNAME/itglue-cli.git
cd itglue-cli
  3. Install dependencies: 
    npm install
  4. Create a .env file with your IT Glue credentials: 
    ITGLUE_API_KEY=ITG.your-api-key-here
ITGLUE_REGION=us
  5. Build the project: 
    npm run build
  6. Link the CLI for local testing: 
    npm link

Development Workflow

Branch Naming

  • Feature branches: feature/description
  • Bug fixes: fix/description
  • Documentation: docs/description
  • Refactoring: refactor/description

Making Changes

  1. Create a new branch:

    git checkout -b feature/my-new-feature

  2. Make your changes following our coding standards

  3. Build and test:

    npm run build
npm run typecheck
npm run lint
npm test

  4. Commit your changes:

    git add .
git commit -m "feat: add new feature"

    Follow Conventional Commits:

    • feat: New features
    • fix: Bug fixes
    • docs: Documentation changes
    • refactor: Code refactoring
    • test: Test changes
    • chore: Build process or tooling changes

  5. Push to your fork:

    git push origin feature/my-new-feature

  6. Create a Pull Request on GitHub

Coding Standards

TypeScript

  • Use TypeScript for all source code
  • Maintain strict type checking
  • Avoid any types when possible
  • Use meaningful variable and function names

Code Style

  • Follow the existing code style
  • Use ESLint for linting: npm run lint
  • Format code consistently
  • Add comments for complex logic

Testing

  • Write tests for new features
  • Ensure existing tests pass
  • Aim for good test coverage
  • Test both success and error cases

Pull Request Guidelines

Before Submitting

  • Code builds without errors
  • All tests pass
  • Linting passes
  • Type checking passes
  • Documentation updated (if needed)
  • CHANGELOG.md updated

PR Description

Include in your PR description:

  • Summary of changes
  • Motivation and context
  • Related issue numbers
  • Testing performed
  • Breaking changes (if any)

Review Process

  1. Maintainers will review your PR
  2. Address any requested changes
  3. Once approved, a maintainer will merge

Adding New Commands

When adding a new command:

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

Example Command Structure

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

export const myCommand = new Command('my-resource')
  .description('Manage my resources');

myCommand
  .command('search')
  .description('Search for resources')
  .option('--format <format>', 'Output format (json|table)', 'json')
  .action(async (options) => {
    try {
      const client = createClient();
      const result = await client.request('/my-resources', {});

      if (options.format === 'table') {
        output(result.data, 'table', {
          head: ['ID', 'Name'],
          mapper: (item: any) => [item.id, item.name],
        });
      } else {
        output(result, options.format as OutputFormat);
      }
    } catch (error) {
      outputError(error instanceof Error ? error.message : String(error));
      process.exit(1);
    }
  });

Documentation

  • Update README.md for user-facing changes
  • Update CHANGELOG.md following Keep a Changelog
  • Add JSDoc comments for public APIs
  • Include usage examples

Testing Guidelines

Manual Testing

Test your changes with real IT Glue API:

npm run build
npm link
itglue <your-command> --format table

Automated Testing

Write unit tests using Vitest:

npm test
npm run test:watch

Questions?

If you have questions:

  • Open a GitHub issue
  • Check existing issues and PRs
  • Review the documentation

License

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

Recognition

Contributors will be recognized in our README and release notes. Thank you for helping improve IT Glue CLI!