Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
247 lines (173 loc) · 6.03 KB

CONTRIBUTING.md

File metadata and controls

247 lines (173 loc) · 6.03 KB

Contributing to payments-mcp

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

Repository Structure

src/
├── cli.ts                    # CLI entry point with Commander.js
├── installer.ts              # Main orchestrator class
├── types/
│   └── index.ts             # TypeScript interfaces and types
├── services/                # Business logic layer
│   ├── versionService.ts   # Version checking and comparison
│   ├── downloadService.ts  # Package download and extraction
│   ├── installService.ts   # npm/electron installation
│   └── configService.ts    # MCP client configuration
└── utils/                  # Utility layer
    ├── logger.ts          # Colored terminal output
    ├── httpUtils.ts       # HTTP client with retry logic
    ├── fileUtils.ts       # Safe file operations
    └── pathUtils.ts       # Cross-platform path utilities

Development Setup

Prerequisites

  • Node.js 22.0.0 or higher
  • npm (included with Node.js)
  • Git

Installation

  1. Fork the repository on GitHub

  2. Clone your fork locally:

    git clone https://github.com/YOUR_USERNAME/payments-mcp.git
cd payments-mcp

  3. Install dependencies:

    npm install

  4. Build the project:

    npm run build

  5. Test locally:

    npm run dev

Pull Request Workflow

  1. Create a Feature Branch

    git checkout -b feature/your-feature-name

  2. Make Your Changes

    • Write clear, concise commit messages
    • Add tests for new functionality
    • Update documentation as needed

  3. Test Your Changes

    npm test
npm run lint
npm run build

  4. Commit Your Changes

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

  5. Push to Your Fork

    git push origin feature/your-feature-name

  6. Create a Pull Request

    • Go to the GitHub repository
    • Click "New Pull Request"
    • Fill out the pull request template
    • Request review from maintainers

Setting up GitHub Signed Commits

Signed commits are required for all contributions. Follow these steps:

  1. Generate a GPG key (if you don't have one):

    gpg --full-generate-key

  2. List your GPG keys:

    gpg --list-secret-keys --keyid-format LONG

  3. Export your public key:

    gpg --armor --export YOUR_KEY_ID

  4. Add the GPG key to your GitHub account:

    • Go to GitHub Settings > SSH and GPG keys
    • Click "New GPG key"
    • Paste your public key

  5. Configure Git to use your GPG key:

    git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true

For more details, see GitHub's documentation on signing commits.

Publishing New Versions

This project uses a standard tag-based release workflow. To publish a new version:

1. Bump the version

Use npm's built-in version command to update package.json and create a git tag:

# For bug fixes (1.0.0 → 1.0.1)
npm version patch

# For new features (1.0.0 → 1.1.0)
npm version minor

# For breaking changes (1.0.0 → 2.0.0)
npm version major

This automatically:

  • Updates package.json and package-lock.json
  • Creates a git commit with the version change
  • Creates a git tag (e.g., v1.0.1)

2. Push the tag

git push && git push --tags

3. Automatic deployment

Once the tag is pushed, the GitHub Actions workflow will automatically:

  • Run tests and linting
  • Build the project
  • Verify the version matches the tag
  • Publish to NPM with provenance

Note: The workflow only triggers on tags matching the pattern v*.*.* (e.g., v1.0.0, v2.1.3).

Code Guidelines

TypeScript Standards

  • Use TypeScript for all new code
  • Follow existing code style and patterns
  • Use proper type definitions
  • Avoid any types when possible

Testing

  • Write unit tests for new functionality
  • Maintain or improve test coverage
  • Use Jest for testing framework
  • Test files should be in __tests__ directories

Error Handling

  • Use descriptive error messages
  • Handle edge cases appropriately
  • Follow the existing error handling patterns

Logging

  • Use the provided Logger utility
  • Include appropriate log levels (info, debug, error)
  • Provide helpful debugging information

Project Architecture

The project follows a layered architecture:

  1. CLI Layer (cli.ts) - Command-line interface
  2. Orchestrator (installer.ts) - Coordinates installation workflow
  3. Services Layer (src/services/) - Business logic
  4. Utilities Layer (src/utils/) - Foundational functionality

See the main README for detailed architecture documentation.

Release Process

Releases are handled by maintainers through GitHub Actions workflows:

  1. Dry Run: Test the release process
  2. Production Deploy: Publish to npm and create GitHub release

Issue Reporting

When reporting issues:

  1. Search existing issues first to avoid duplicates
  2. Use the issue template if available
  3. Provide detailed information:
    • Node.js version
    • Operating system
    • Steps to reproduce
    • Expected vs actual behavior
    • Error messages or logs

Getting Help

  • Documentation: Check the README and service documentation
  • Issues: Create a GitHub issue for bugs or feature requests
  • Security: Use our security policy for vulnerability reports

Code of Conduct

This project follows the Coinbase Code of Conduct. Please be respectful and constructive in all interactions.

License

By contributing to payments-mcp, you agree that your contributions will be licensed under the Apache-2.0 License.