Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
103 lines (71 loc) · 2.71 KB

CONTRIBUTING.md

File metadata and controls

103 lines (71 loc) · 2.71 KB

Contributing to perp-cli

Thank you for your interest in contributing to perp-cli! This guide will help you get started.

Getting Started

Prerequisites

  • Node.js >= 20
  • pnpm >= 10

Setup

git clone https://github.com/hypurrquant/perp-cli.git
cd perp-cli
pnpm install
pnpm run build

Running locally

# CLI
node dist/index.js status

# MCP server
node dist/mcp-server.js

Running tests

# Unit tests (required before submitting a PR)
pnpm test

# Integration tests (optional — requires exchange API keys)
pnpm run test:integration

How to Contribute

Before you start

  1. Search existing issues to avoid duplicating work
  2. Open an issue first for large changes or new features — let's discuss before you code
  3. Small PRs are preferred — easier to review and merge

Workflow

  1. Fork the repository
  2. Create a branch from main (git checkout -b feat/my-feature)
  3. Make your changes
  4. Run pnpm test and ensure all tests pass
  5. Run pnpm run build and ensure it compiles
  6. Commit with a clear message (e.g. feat: add market depth command)
  7. Push to your fork and open a Pull Request

Commit message convention

We follow a lightweight Conventional Commits style:

  • feat: — new feature
  • fix: — bug fix
  • refactor: — code change that neither fixes a bug nor adds a feature
  • docs: — documentation only
  • test: — adding or updating tests
  • chore: — maintenance (deps, CI, etc.)

Test Policy

Test type Required for PR? Notes
Unit tests (pnpm test) Yes Must pass
Integration — read-only Optional Maintainers will re-run if needed
Integration — live/mainnet No Never required from contributors

Note: Integration tests hit live exchanges and may require API keys. Contributors are NOT expected to run them. Maintainers will verify these separately.

Documentation

If your PR changes any of the following, please update the relevant docs:

  • CLI commands or flags → update README.md
  • --json output shape → update API_RESPONSE_SPEC.md
  • MCP tool name or schema → update README.md (AI Agent section)

Code Style

  • TypeScript with strict mode
  • ESM modules (import/export)
  • Avoid any types where possible
  • Keep functions focused and small

Security

  • Never commit API keys, private keys, or secrets
  • If you find a security vulnerability, do NOT open a public issue — see SECURITY.md
  • Be careful with exchange API calls that can modify positions or move funds

Questions?

Open a Discussion or comment on the relevant issue.