Files
opencode-primer/CONTRIBUTING.md
Wesam Abousaid ccac453cdb chore(oss): add OSS infrastructure — CoC, security, contributing, CI
Community and contributor support:
- CONTRIBUTING.md: what we welcome, what we don't, style guide,
  templates for MCP walkthroughs and specialized-agent prompts.
- CODE_OF_CONDUCT.md: Contributor Covenant 2.1.
- SECURITY.md: scope (this is a docs repo, not application code), how
  to report a vulnerability in the example plugins or in misleading
  documentation, where OpenCode-core bugs should go instead.

GitHub plumbing:
- .github/PULL_REQUEST_TEMPLATE.md: type, sources, hygiene checklist.
- .github/ISSUE_TEMPLATE/{bug_report,feature_request}.md and config.yml
  that redirects OpenCode-tool issues to the right place.
- .github/workflows/lint-docs.yml: three jobs on every push and PR —
  markdownlint, link check (with sensible ignore patterns for
  ../../issues, security advisories, localhost), codespell with a
  project-specific ignore list.

Lint/style configs:
- .markdownlint.json + .markdownlintignore: ATX headings, ordered list
  numbering, line-length and inline-HTML rules tuned for our content.
- .editorconfig: LF, UTF-8, 2-space indent, trim trailing whitespace
  except in markdown (where trailing spaces are line breaks).
2026-05-18 20:00:51 +02:00

82 lines
4.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Contributing
Thank you for considering a contribution. This repo is a community-maintained guide to [OpenCode](https://opencode.ai) — every typo fix, fact correction, and new example helps the next reader.
## What we welcome
| Contribution | What's helpful |
|---|---|
| **Fact corrections** | OpenCode moves fast. If something here is out of date, fix it and cite the source. |
| **New MCP walkthroughs** | A short page in [`mcp-servers/`](mcp-servers/) with verified setup steps, example prompts, and gotchas. |
| **New specialized-agent prompts** | A new role under [`specialized-agents/system-prompts/`](specialized-agents/system-prompts/) + a one-page description. |
| **Better examples** | Real-world patterns that worked for you. |
| **Typo and grammar fixes** | Just send the PR. |
| **Image / diagram contributions** | Drop PNG/SVG in [`Images/`](Images/) and reference them inline. |
## What we don't accept
- **Unverified claims.** Every factual statement must trace back to [opencode.ai/docs](https://opencode.ai/docs/), the [OpenCode GitHub repo](https://github.com/anomalyco/opencode), or a primary source. No "I heard that…".
- **Marketing language.** This guide is practical, not a sales pitch.
- **Affiliate links or sponsored content** without prior agreement.
- **AI-generated content that hasn't been read and verified by you.** If you used an AI to draft, that's fine — but read it carefully, fact-check, and remove fluff before submitting.
## How to contribute
1. **Open an issue first** for non-trivial changes (new sections, restructuring) so we can align on scope.
2. **Fork → branch → PR.** One topic per PR; smaller is better.
3. **Match the existing style.** See [AGENTS.md](AGENTS.md) for style conventions (markdown, tone, link form).
4. **Cite your sources.** If you're updating a fact, include a link to the source in the PR description.
5. **Update the "Last reviewed" date** at the bottom of the README if you've made material changes.
## Style basics
- Short lines, plain English.
- Lead with the mental model, then the syntax, then the example.
- Comparison tables when there's a choice to make.
- Code fences with language tags. JSON examples should be valid `opencode.json` snippets.
- Emoji callouts: `> 💡 Pro Tip`, `> ⚠️ Warning`, `> 🆕 New`, `> 📚 Further reading`.
## Tips for adding a new MCP walkthrough
A good walkthrough has:
1. **When to reach for it** — one-line use case
2. **Setup** — exact JSON snippet for `opencode.json` and any auth steps
3. **Example prompts** — 2–3 realistic prompts (not "hello world")
4. **What it can do / won't do** — set expectations
5. **Gotchas** — things you wish you'd known
6. **Resources** — links to the upstream project
See [`mcp-servers/playwright.md`](mcp-servers/playwright.md) as a template.
## Tips for adding a new specialized-agent prompt
A good system prompt has:
1. **Frontmatter** with `description`, `mode`, `model`, `temperature`, `permission` — use the format in [`docs/agents.md`](docs/agents.md).
2. **Principles** — 3–5 numbered, prescriptive items. What the agent prioritizes.
3. **Workflow** — concrete steps the agent should follow.
4. **Defaults** — the stack and tools the agent uses.
5. **What I won't do** — explicit constraints. This is what makes specialized agents different from a generic LLM.
6. **Communication style** — how the agent talks (terse, surfaces trade-offs, etc.).
Add the matching short description under [`specialized-agents/descriptions/`](specialized-agents/descriptions/) and update the table in [`specialized-agents/README.md`](specialized-agents/README.md).
## Local check
There's no build system to run, but a quick mental checklist before submitting:
- [ ] All links resolve (in-page anchors and external URLs)
- [ ] Code fences have language tags
- [ ] No trailing whitespace
- [ ] No emoji clutter
- [ ] Facts cite a source
## Questions
Open a [GitHub Discussion](../../discussions) or an [issue](../../issues). Drive-by PRs are welcome too — we'll suggest changes in review.
---
*Thanks for making this resource better.*