Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
184 lines (129 loc) · 5.93 KB

CONTRIBUTING.md

File metadata and controls

184 lines (129 loc) · 5.93 KB

Contributing to KinBot

Thanks for considering contributing to KinBot! Whether it's a bug fix, new provider, feature, or docs improvement, every contribution helps.

Getting Started

Prerequisites

  • Bun ≥ 1.0
  • Git
  • At least one AI provider API key (Anthropic, OpenAI, Gemini, etc.)

Local Development Setup

git clone https://github.com/MarlBurroW/kinbot.git
cd kinbot
bun install
bun run db:migrate
bun run dev

This starts both the Vite dev server (frontend) and the Bun server (backend) with hot reload. Open http://localhost:5173 in your browser.

Project Structure

src/
├── client/          # React frontend (Vite + Tailwind)
├── server/          # Bun + Hono backend
│   ├── providers/   # AI provider adapters
│   ├── channels/    # Chat platform adapters (Telegram, Discord, etc.)
│   └── ...
├── shared/          # Shared types & utilities
site/                # Landing page (React + Vite + Tailwind v4)

Useful Commands

Command Description
bun run dev Start dev server (client + server)
bun run build Production build
bun run db:generate Generate DB migrations (Drizzle)
bun run db:migrate Run pending migrations
bun test Run tests

How to Contribute

Reporting Bugs

Use the bug report template. Include:

  • Steps to reproduce
  • Expected vs actual behavior
  • Browser, OS, and KinBot version

Requesting Features

Use the feature request template. Describe the problem you're solving, not just the solution you want.

Submitting Code

  1. Fork the repository
  2. Create a branch from main: git checkout -b feat/my-feature
  3. Make your changes with clear, focused commits
  4. Test your changes: bun test and manual testing
  5. Push and open a Pull Request

Adding a Provider

Providers are self-contained adapters in src/server/providers/. To add one:

  1. Create src/server/providers/<name>.ts (use an existing one as template)
  2. Implement the ProviderDefinition interface: testConnection() + listModels()
  3. Register it in src/server/providers/index.ts
  4. Add the type to the ProviderType union in src/shared/types.ts
  5. Commit: feat: add <name> provider

For OpenAI-compatible providers, reuse the pattern from openai.ts with a custom baseUrl.

Adding a Channel

Channel adapters live in src/server/channels/ and implement the ChannelAdapter interface:

  1. Create the adapter file in src/server/channels/
  2. Implement: start(), stop(), sendMessage(), validateConfig(), getBotInfo()
  3. Register it in src/server/channels/index.ts
  4. Add the platform to ChannelPlatform in src/shared/types.ts
  5. Commit: feat: add <platform> channel

Submitting a Store Plugin

The store/ directory contains curated community plugins that users can install directly from the KinBot UI. Here's how to submit yours.

Scaffold a New Plugin

bun store:create my-plugin -d "What it does" -a "Your Name" -i "🚀"

This creates store/my-plugin/ with the three required files:

  • plugin.json - manifest (metadata, config schema, permissions)
  • index.ts - entry point
  • README.md - documentation shown in the Store UI

Plugin Requirements

  • Name must match [a-z0-9][a-z0-9-]* and be unique in the store
  • Manifest must include name, version, description, and main
  • README is required and displayed in the plugin detail modal
  • Permissions must be minimal. Only request what you need (e.g., http:api.example.com instead of http:*)
  • No external dependencies. Plugins run in-process with Bun, use ctx.http for HTTP requests
  • Config fields must have type, label, and description

Validate Locally

bun store:validate my-plugin

This runs the same checks as CI: manifest schema, required files, TypeScript syntax, config field validation.

Test Locally

Copy your plugin to the plugins/ directory and restart KinBot:

cp -r store/my-plugin plugins/
bun run dev

Verify it loads, the config UI renders correctly, and tools work as expected.

Submit a PR

  1. Fork the repo and create a branch: git checkout -b store/my-plugin
  2. Add only your plugin directory under store/
  3. Push and open a PR. The store-plugins CI workflow validates your manifest automatically.
  4. A maintainer will review the code, test the plugin, and merge if it looks good.

Tips

  • Look at store/rss-reader/ as a reference implementation
  • Keep plugins focused: one clear purpose per plugin
  • Write helpful README examples so users know what prompts to try
  • Use ctx.log for debugging, ctx.storage for persistence, ctx.config for user settings
  • See the Plugin Development Guide for the full API reference

Code Style

  • TypeScript strict mode
  • Imports use the @/ alias (configured in tsconfig)
  • Logging via createLogger('scope:name')
  • Prefer fetch over heavy SDK dependencies
  • Keep files focused: one provider/channel per file

Commit Messages

Follow conventional commits:

  • feat: add <thing> for new features
  • fix: resolve <issue> for bug fixes
  • docs: update <what> for documentation
  • site: <description> for landing page changes
  • refactor:, test:, ci:, chore: as needed

Landing Page

The landing page lives in site/ and deploys automatically to GitHub Pages on push to main.

cd site
bun install
bun run dev      # Local dev server
bun run build    # Test production build

License

By contributing, you agree that your contributions will be licensed under the AGPL-3.0 License.

Questions?

Open a discussion or an issue. We're happy to help!