mirror of
https://github.com/Heretek-AI/awesome-opencode.git
synced 2026-11-07 02:35:58 -10:00
John SmithandClaude Opus 5.5
91287042b8
docs/policy.md is the reference the bots link to (admission, V2 rule, V1 sunset, health and removal, discovery, automation map). contributing.md documents the issue form, scaffolder and fields. The review-loop prompts now defer schema/duplicate/V2 checks to CI, drop the 6-month activity rule, and require merging through PRs instead of pushing to main. Translated READMEs link to this repo's contributing guide. Co-Authored-By: Claude Opus 5.5 <[email protected]>
72 lines
4.0 KiB
Markdown
72 lines
4.0 KiB
Markdown
# Contribution Guidelines
|
||
|
||
Thank you for contributing to `awesome-opencode`! Every entry is a YAML file under `data/`; the README and the [search site](https://heretek-ai.github.io/awesome-opencode/) are generated from those files. **Never edit `README.md` directly**: PRs that do are rejected by the `validate` check.
|
||
|
||
## Option 1: the issue form (recommended)
|
||
|
||
[Open an "Add an entry" issue](https://github.com/Heretek-AI/awesome-opencode/issues/new?template=add-entry.yml). A bot validates the fields, checks OpenCode V2 compatibility for plugins, comments with the result, and opens the pull request for you. To fix something, edit the issue; the PR updates itself.
|
||
|
||
## Option 2: a pull request
|
||
|
||
1. Fork and clone the repo, then run `npm ci`.
|
||
2. Create the entry. The scaffolder writes a correctly formatted file and runs the V2 check:
|
||
|
||
```bash
|
||
npm run new -- --category plugins --repo https://github.com/owner/repo \
|
||
--tagline "Short summary" --topics memory,context [--npm package-name] [--path packages/x]
|
||
```
|
||
|
||
Or write `data/<category>/<name>.yaml` by hand (kebab-case filename):
|
||
|
||
```yaml
|
||
name: Quota Board
|
||
repo: https://github.com/owner/opencode-quota-board
|
||
npm: opencode-quota-board
|
||
tagline: Provider quotas and reset countdowns in the OpenCode sidebar
|
||
description: Adds quota bars, reset countdowns and credit balances to the OpenCode V2 TUI.
|
||
kind: plugin
|
||
topics:
|
||
- cost
|
||
- providers
|
||
compat: v2
|
||
```
|
||
|
||
3. Run `npm run validate`, then open the PR. CI runs the same checks and comments with anything to fix.
|
||
|
||
## Fields
|
||
|
||
| Field | Required | Notes |
|
||
| :--- | :--- | :--- |
|
||
| `name` | yes | Max 80 characters |
|
||
| `repo` | yes | Repository **root** URL (GitHub, GitLab, Codeberg, Gitee; gists allowed). No `/tree/`, `/blob/`, npm pages or websites |
|
||
| `path` | no | Folder inside a monorepo, e.g. `packages/my-plugin` |
|
||
| `npm` | no | Package name; strongly recommended for plugins (used for the V2 check and health checks) |
|
||
| `tagline` | yes | Max 120 characters. Quote it if it contains `: ` (e.g. `tagline: "Plain: no jargon"`) |
|
||
| `description` | yes | Max 1500 characters |
|
||
| `kind` | yes | `plugin`, `theme`, `agent`, `skill`, `mcp-server`, `client`, `tool`, `config`, `guide` or `fork` |
|
||
| `topics` | yes | 1–3 of: memory, context, orchestration, workflow, providers, cost, notifications, sessions, code-quality, security, git, remote, web, ui, voice, media, docs, environment, observability, integrations, code-intel, prompting, domain. The first is used for README grouping |
|
||
| `compat` | plugins | `v2`, `v1` or `unknown`; CI verifies it. Other categories may omit it |
|
||
| `also` | no | Secondary kinds, e.g. `[mcp-server]` for a plugin that also ships an MCP server |
|
||
| `scope`, `tags`, `min_version`, `homepage`, `installation` | no | See [docs/schema-design.md](docs/schema-design.md) |
|
||
|
||
Unknown fields are rejected, so typos like `repository:` or `install:` are caught.
|
||
|
||
Which category? `plugins` for OpenCode plugin packages, `themes` for color themes, `agents` for agent configs and skill packs, `projects` for clients, GUIs, MCP servers, tools and forks, `resources` for guides, configs and starters.
|
||
|
||
## What gets accepted
|
||
|
||
See the [catalog policy](docs/policy.md). In short:
|
||
|
||
- **Relevant**: works with OpenCode.
|
||
- **Public**: the repository is public and not archived.
|
||
- **V2 for new plugins**: depends on `@opencode/plugin` and uses `Plugin.define`. V1 plugin PRs are held with the `needs-v2` label; a nightly job re-checks them and unblocks the PR automatically once the plugin migrates.
|
||
- **Unique**: one entry per repository (per `path` for monorepos).
|
||
- **No crypto**: no cryptocurrency, token or trading projects.
|
||
|
||
## What happens after you submit
|
||
|
||
1. **`validate` check**: schema, duplicates, generated-file edits and the V2 check. Required to merge.
|
||
2. **Triage**: a bot labels the PR (`ready`, `needs-v2`, `needs-metadata` or `needs-human`) and comments with the results.
|
||
3. **Maintainer review and merge.**
|
||
4. **README, registry and search site regenerate automatically.**
|