Skip to content

Revision: 2026-09-26

Contributing to Deposium CLI

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

📋 Table of Contents

🤝 Code of Conduct

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help others learn and grow
  • Follow the project's coding standards

🛠️ Development Setup

Prerequisites

  • Node.js: ^22.13.0 or >=24; the Node 22 floor follows Inquirer 13, Node 23 is not supported, and Node 24 is recommended for development
  • npm: The version bundled with a supported Node.js release for development; see the release guide for staged publishing requirements
  • Git: For version control

Initial Setup

# Clone the repository
git clone https://github.com/theseedship/deposium_CLI.git
cd deposium_CLI

# Install dependencies
npm install

# Install Husky hooks
npm run prepare

# Verify setup
npm run typecheck
npm run lint
npm run build

🔄 Development Workflow

1. Create a Feature Branch

Always create a new branch from main:

git checkout main
git pull origin main
git checkout -b feat/your-feature-name

Branch naming conventions:

  • feat/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation changes
  • refactor/ - Code refactoring
  • test/ - Test additions/modifications
  • chore/ - Maintenance tasks

2. Make Your Changes

Follow these guidelines:

  • Write clear, descriptive commit messages
  • Keep commits atomic and focused
  • Add tests for new features
  • Update documentation as needed
  • Follow the existing code style

3. Commit Your Changes

Our Git hooks will automatically run quality checks:

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

Pre-commit hook will:

  • ✅ Run ESLint with auto-fix
  • ✅ Run Prettier to format code
  • ✅ Only on staged files (fast!)

Pre-push hook will:

  • ✅ Run TypeScript type checking
  • ✅ Run full build to ensure no errors

4. Push and Create Pull Request

git push origin feat/your-feature-name

Then create a PR on GitHub with:

  • Clear title describing the change
  • Detailed description of what and why
  • Reference any related issues
  • Screenshots/examples if applicable

📏 Code Quality Standards

TypeScript

  • Use TypeScript for all code
  • Enable strict mode in tsconfig.json
  • Avoid any types when possible
  • Document complex types and interfaces

ESLint Rules

We enforce strict linting rules:

# Run linter
npm run lint

# Auto-fix issues
npm run lint:fix

Key rules:

  • No unused variables
  • Consistent code style
  • Proper error handling
  • Complexity limits (max 15)
  • Max function length (100 lines)
  • No floating promises

Code Formatting

We use Prettier for consistent formatting:

# Format all files
npm run format

# Check formatting
npx prettier --check .

Prettier config:

  • Single quotes
  • Semicolons required
  • 2-space indentation
  • 100 character line width
  • LF line endings

Type Checking

All code must pass TypeScript type checking:

npm run typecheck

🔍 Pull Request Process

Before Submitting

Ensure your PR passes all checks:

  1. Lint: npm run lint ✅
  2. Format: npx prettier --check . ✅
  3. Type Check: npm run typecheck ✅
  4. Build: npm run build ✅
  5. Tests: npm test ✅

PR Template

Use this template for your PR description:

## Summary

Brief description of the changes

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Changes Made

- List of specific changes
- With bullet points

## Testing

- How to test these changes
- Any special testing considerations

## Checklist

- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added to complex code
- [ ] Documentation updated
- [ ] No new warnings generated
- [ ] Tests added/updated
- [ ] All tests passing

Code Review

  • Address all review comments
  • Keep discussions professional and constructive
  • Make requested changes in new commits
  • Squash commits before merging (if requested)

Merging

PRs will be merged when:

  • ✅ All CI/CD checks pass
  • ✅ Code review approved
  • ✅ No merge conflicts
  • ✅ Documentation updated
  • ✅ Tests passing

🪝 Git Hooks

We use Husky for automated quality checks:

Pre-commit Hook

Runs on every commit:

# .husky/pre-commit
- ESLint (auto-fix)
- Prettier (auto-format)
- Only on staged files (via lint-staged)

To bypass (emergency only):

git commit --no-verify -m "emergency fix"

Pre-push Hook

Runs before pushing:

# .husky/pre-push
- TypeScript type checking
- Full build verification

To bypass (not recommended):

git push --no-verify

🚀 CI/CD Pipeline

Every PR triggers automated checks on GitHub Actions:

Quality Job

  • ✅ ESLint verification
  • ✅ Prettier check
  • ✅ TypeScript type checking
  • ✅ Tests execution
  • 🔄 Quality and build checks run on Node 22.13.0 and Node 24.x; security and publishing use Node 24.x

Build Job

  • ✅ Build verification
  • ✅ Artifact validation

Security Job

  • ✅ npm audit (dependency vulnerabilities)
  • ✅ TruffleHog (secret detection)

Viewing CI Results

  1. Go to your PR on GitHub
  2. Check "Checks" tab
  3. View detailed logs for any failures
  4. Fix issues and push again

Release Process

See the release and staged npm publishing guide for publication checks and required approvals. Merging a new package version into main automatically stages it on npm; maintainer approval with npm 2FA is required to publish it. A merge without a version change does not create a release.

📝 Commit Message Guidelines

Follow Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Formatting, missing semi-colons, etc.
  • refactor: Code restructuring
  • test: Adding tests
  • chore: Maintenance

Examples:

feat(auth): add API key authentication system

Implement secure API key authentication for all CLI commands.
Includes login, logout, and status commands with retry logic.

Closes #123

fix(search): handle empty query results gracefully

Previously crashed on empty results. Now shows friendly message.

🧪 Testing

Run Tests

# Run all tests
npm test

# Watch mode
npm run test:watch

Writing Tests

  • Place tests in src/__tests__/ directory: *.test.ts
  • Use descriptive test names
  • Test edge cases and error conditions
  • Aim for high coverage on critical paths

🐛 Reporting Issues

When reporting bugs:

  1. Check existing issues first
  2. Provide clear title and description
  3. Include reproduction steps
  4. Add error messages/stack traces
  5. Specify environment details
  6. Add screenshots if helpful

💡 Feature Requests

For new features:

  1. Search existing feature requests
  2. Describe the problem it solves
  3. Provide use case examples
  4. Consider implementation approach
  5. Be open to discussion

📚 Additional Resources

🙏 Thank You!

Your contributions make Deposium CLI better for everyone. We appreciate your time and effort!

Questions? Open an issue or reach out to the maintainers.