Contributing to DeepSeek CLI

Thank you for your interest in contributing to DeepSeek CLI!

Getting Started • Development Setup • Code Style • Testing • Submitting Changes

🤝 How to Contribute

We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or suggesting ideas, your help is appreciated.

Types of Contributions

🐛 Bug Reports: Report issues and help us fix them
✨ Feature Requests: Suggest new features and improvements
🔧 Code Contributions: Submit pull requests with code changes
📚 Documentation: Improve guides, examples, and API documentation
🧪 Testing: Help test features and report issues
💡 Ideas: Share ideas for future improvements

🚀 Getting Started

Prerequisites

Node.js: Version 18 or higher
Git: Latest version
DeepSeek API Key: For testing (get one from DeepSeek Platform)

Quick Setup

Fork the repository

# Fork on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/deepseek-cli.git
cd deepseek-cli

Set up development environment

# Install dependencies
yarn install

# Build the project
yarn build

# Link for local development
yarn link

Configure your environment

# Set your API key for testing
deepseek config --set apiKey=YOUR_API_KEY

# Test the installation
deepseek test

🔧 Development Setup

Project Structure

deepseek-cli/
├── src/                    # Source code
│   ├── api/               # DeepSeek API client
│   ├── cli/               # CLI commands and logic
│   ├── config/            # Configuration management
│   ├── analysis/          # Code analysis tools
│   ├── workflow/          # Workflow automation
│   ├── ui/                # UI and theming
│   └── utils/             # Utility functions
├── dist/                  # Built files
├── docs/                  # Documentation
├── scripts/               # Build and utility scripts
├── tests/                 # Test files
└── examples/              # Example configurations

Development Commands

# Install dependencies
yarn install

# Build the project
yarn build

# Run in development mode
yarn dev

# Run tests
yarn test

# Run tests with coverage
yarn test:coverage

# Run tests in watch mode
yarn test:watch

# Lint code
yarn lint

# Format code
yarn format

# Clean build artifacts
yarn clean

# Link for local development
yarn link

# Unlink
yarn unlink

Environment Configuration

Create a .env file for development:

# .env
DEEPSEEK_API_KEY=your-api-key-here
DEEPSEEK_MODEL=v3
DEEPSEEK_THEME=auto
DEEPSEEK_LOG_LEVEL=debug

📝 Code Style

TypeScript Guidelines

Strict Mode: Always use TypeScript strict mode
Type Annotations: Provide explicit types for function parameters and return values
Interfaces: Use interfaces for object shapes and API contracts
Enums: Use enums for constants and configuration options
Generics: Use generics for reusable components and utilities

Code Formatting

We use Prettier and ESLint for code formatting and linting:

# Format code
yarn format

# Lint code
yarn lint

# Fix linting issues
yarn lint --fix

Naming Conventions

Files: Use kebab-case for file names (deep-seek-api.ts)
Classes: Use PascalCase (DeepSeekAPI)
Functions: Use camelCase (sendMessage)
Constants: Use UPPER_SNAKE_CASE (MAX_TOKENS)
Interfaces: Use PascalCase with I prefix (IConfig)
Types: Use PascalCase (ApiResponse)

Documentation

JSDoc: Add JSDoc comments for all public functions and classes
README: Update README.md for new features
Examples: Provide usage examples for new functionality
Comments: Add inline comments for complex logic

Example Code Style

/**
 * DeepSeek API client for making requests to the DeepSeek API
 * 
 * @author samir.tan.it@gmail.com
 * @created 2025-06-28
 */
export class DeepSeekAPI {
  private readonly client: AxiosInstance;
  private readonly logger: Logger;

  /**
   * Create a new DeepSeek API client
   * 
   * @param configManager - Configuration manager instance
   * @param logger - Logger instance for debugging
   */
  constructor(
    private configManager: ConfigManager,
    logger?: Logger
  ) {
    this.logger = logger || new Logger();
    this.client = this.createClient();
  }

  /**
   * Send a message to the DeepSeek API
   * 
   * @param message - The message to send
   * @returns Promise resolving to the API response
   * @throws {Error} When API request fails
   */
  async sendMessage(message: string): Promise<string> {
    try {
      // Implementation here
    } catch (error) {
      this.logger.error('Failed to send message', { error });
      throw new Error(`API request failed: ${error.message}`);
    }
  }
}

🧪 Testing

Test Structure

tests/
├── unit/                  # Unit tests
│   ├── api/              # API tests
│   ├── cli/              # CLI tests
│   └── utils/            # Utility tests
├── integration/          # Integration tests
├── e2e/                  # End-to-end tests
└── fixtures/             # Test data and fixtures

Writing Tests

We use Jest for testing. Follow these guidelines:

/**
 * DeepSeekAPI tests
 */
describe('DeepSeekAPI', () => {
  let api: DeepSeekAPI;
  let mockConfigManager: jest.Mocked<ConfigManager>;
  let mockLogger: jest.Mocked<Logger>;

  beforeEach(() => {
    mockConfigManager = {
      get: jest.fn(),
      set: jest.fn(),
    } as any;
    
    mockLogger = {
      info: jest.fn(),
      error: jest.fn(),
      debug: jest.fn(),
    } as any;

    api = new DeepSeekAPI(mockConfigManager, mockLogger);
  });

  describe('sendMessage', () => {
    it('should send message successfully', async () => {
      // Arrange
      const message = 'Hello, DeepSeek!';
      const expectedResponse = 'Hello, human!';
      
      // Mock API response
      jest.spyOn(api as any, 'makeRequest').mockResolvedValue(expectedResponse);

      // Act
      const result = await api.sendMessage(message);

      // Assert
      expect(result).toBe(expectedResponse);
      expect(mockLogger.info).toHaveBeenCalledWith('Message sent successfully');
    });

    it('should handle API errors gracefully', async () => {
      // Arrange
      const message = 'Hello, DeepSeek!';
      const error = new Error('API Error');
      
      jest.spyOn(api as any, 'makeRequest').mockRejectedValue(error);

      // Act & Assert
      await expect(api.sendMessage(message)).rejects.toThrow('API request failed: API Error');
      expect(mockLogger.error).toHaveBeenCalledWith('Failed to send message', { error });
    });
  });
});

Running Tests

# Run all tests
yarn test

# Run tests with coverage
yarn test:coverage

# Run tests in watch mode
yarn test:watch

# Run specific test file
yarn test src/api/DeepSeekAPI.test.ts

# Run tests matching pattern
yarn test --testNamePattern="sendMessage"

Test Coverage

We aim for high test coverage:

Unit Tests: 90%+ coverage
Integration Tests: 80%+ coverage
Critical Paths: 100% coverage

🔄 Submitting Changes

Before Submitting

Ensure tests pass
```
yarn test
yarn lint
yarn build
```
Update documentation
- Update README.md for new features
- Add JSDoc comments for new functions
- Update USAGE_GUIDE.md if needed
Check code style
```
yarn format
yarn lint --fix
```

Pull Request Process

Create a feature branch
```
git checkout -b feature/amazing-feature
```
Make your changes
- Write code following our style guidelines
- Add tests for new functionality
- Update documentation

Commit your changes

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

Push to your fork
```
git push origin feature/amazing-feature
```
Create a Pull Request
- Use the PR template
- Describe your changes clearly
- Link any related issues

Commit Message Format

We follow Conventional Commits:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples:

git commit -m "feat: add support for custom prompts"
git commit -m "fix: resolve API timeout issues"
git commit -m "docs: update installation instructions"
git commit -m "test: add unit tests for CodeAnalyzer"

Pull Request Template

## Description
Brief description of the changes

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist
- [ ] Code follows the style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] No breaking changes (or documented)

## Related Issues
Closes #123

🐛 Reporting Issues

Bug Reports

When reporting bugs, please include:

Environment Information
- Operating System
- Node.js version
- DeepSeek CLI version
- Package manager (npm/yarn)
Steps to Reproduce
- Clear, step-by-step instructions
- Minimal example if possible
Expected vs Actual Behavior
- What you expected to happen
- What actually happened
Additional Information
- Error messages and stack traces
- Screenshots if applicable
- Logs with debug level enabled

Feature Requests

When requesting features:

Describe the Problem
- What problem does this feature solve?
- Why is this feature needed?
Propose a Solution
- How should this feature work?
- Any specific requirements or constraints?
Consider Alternatives
- Are there existing ways to achieve this?
- What are the trade-offs?

📚 Documentation

Contributing to Documentation

README.md: Main project documentation
USAGE_GUIDE.md: Detailed usage instructions
API Documentation: JSDoc comments in code
Examples: Code examples and use cases

Documentation Guidelines

Use clear, concise language
Include code examples
Keep documentation up-to-date
Use proper markdown formatting
Add screenshots for UI changes

🏷️ Release Process

Versioning

We follow Semantic Versioning:

MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes (backward compatible)

Release Checklist

🤝 Community Guidelines

Code of Conduct

Be respectful and inclusive
Help others learn and grow
Provide constructive feedback
Follow project guidelines

Communication

Issues: Use GitHub issues for bugs and feature requests
Discussions: Use GitHub discussions for questions and ideas
Discord: Join our community for real-time chat

Recognition

Contributors are recognized in:

README.md contributors section
GitHub contributors page
Release notes
Project documentation

🆘 Getting Help

Resources

📖 Documentation
🐛 Issues
💬 Discussions
📧 Email

Mentorship

New contributors can:

Ask questions in discussions
Request code reviews
Pair program with maintainers
Join community calls

Thank you for contributing to DeepSeek CLI! 🎉

Get Started • View Issues • Join Discussions

Author: samir.tan.it@gmail.com
Created: 2025-06-28
Last Updated: 2025-06-28

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History