Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
207 lines (142 loc) · 3.94 KB

CONTRIBUTING.md

File metadata and controls

207 lines (142 loc) · 3.94 KB

Contributing to Plugin Delivery

Thank you for your interest in contributing to the SperaxOS Plugin Delivery ecosystem! This guide will help you get started.

⚠️ Adding a Plugin? Read This First!

Every plugin requires TWO files or the build will fail:

File Location Required
Plugin definition src/your-plugin.json ✅ Yes
Locale file locales/your-plugin.en-US.json ✅ Yes

Then run:

export OPENAI_API_KEY=your-key
bun run format   # Generates all locale translations
bun run build    # Verify it works

See Submitting a Plugin for full details.

Table of Contents

Code of Conduct

Be respectful, inclusive, and constructive. We're building tools for the crypto/DeFi community together.

Getting Started

Prerequisites

Clone the Repository

git clone https://github.com/nirholas/plugin.delivery.git
cd plugins
bun install

Project Structure

plugins/
├── packages/
│   ├── sdk/          # @sperax/plugin-sdk
│   └── gateway/      # @sperax/chat-plugins-gateway
├── templates/        # Plugin starter templates
├── docs/             # Documentation
├── public/           # Plugin index files
├── src/              # Plugin source files
└── scripts/          # Build scripts

Development Setup

Run Tests

bun run test

Build Plugin Index

bun run build

Local Development

bun run dev

This starts a local Vercel dev server at http://localhost:3000.

Submitting a Plugin

Option 1: Via GitHub Issue

  1. Create a Plugin Submission issue
  2. Provide your manifest URL and details
  3. We'll review and add it to the index

Option 2: Via Pull Request

  1. Fork the repository
  2. Add your plugin to src/your-plugin.json:
{
  "identifier": "your-plugin",
  "author": "your-name",
  "createdAt": "2025-01-01",
  "manifest": "https://your-domain.com/manifest.json",
  "meta": {
    "title": "Your Plugin",
    "description": "What it does",
    "avatar": "🔌",
    "tags": ["category"]
  }
}
  1. Run bun run build to regenerate the index
  2. Submit a PR

Plugin Requirements

  • ✅ Valid JSON manifest
  • ✅ Working API endpoints
  • ✅ Tested in SperaxOS
  • ✅ Clear documentation
  • ✅ No malicious code

Contributing Code

Branch Naming

  • feature/description - New features
  • fix/description - Bug fixes
  • docs/description - Documentation
  • plugin/name - New plugins

Commit Messages

Use conventional commits:

feat: add new plugin type
fix: resolve manifest validation
docs: update SDK guide
plugin: add dexscreener integration

Pull Request Process

  1. Fork and create a branch
  2. Make changes
  3. Run tests: bun run test
  4. Run lint: bun run lint
  5. Submit PR with clear description

Style Guidelines

TypeScript

  • Use strict mode
  • Prefer const over let
  • Use async/await over promises
  • Export types explicitly

JSON

  • 2-space indentation
  • Trailing newline
  • No trailing commas

Documentation

  • Use Markdown
  • Include code examples
  • Keep it concise

Questions?

License

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

Code of Conduct

Please read and follow our Code of Conduct.