Skip to content

Commit 05f9e07

Browse files
blazejpawlakblazejpawlak
committed
docs(community): add CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, and GitHub templates
Adds standard open-source community health files: - CONTRIBUTING.md with dev workflow, quality gates, and architecture overview - CODE_OF_CONDUCT.md (Contributor Covenant 2.1) - SECURITY.md with vulnerability disclosure process and known considerations - .github/ISSUE_TEMPLATE/bug_report.yml and feature_request.yml - .github/PULL_REQUEST_TEMPLATE.md with checklist
1 parent a7386b8 commit 05f9e07

File tree

6 files changed

+350
-0
lines changed

6 files changed

+350
-0
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
name: Bug Report
2+
description: Report a bug or unexpected behavior in opencode-model-fallback
3+
labels: ["bug"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thanks for taking the time to report a bug. Please fill in as much detail as possible.
9+
10+
- type: input
11+
id: version
12+
attributes:
13+
label: Plugin version
14+
placeholder: "e.g. 0.1.0"
15+
validations:
16+
required: true
17+
18+
- type: input
19+
id: opencode-version
20+
attributes:
21+
label: OpenCode version
22+
placeholder: "e.g. 1.2.24"
23+
validations:
24+
required: true
25+
26+
- type: textarea
27+
id: description
28+
attributes:
29+
label: What happened?
30+
description: A clear and concise description of the bug.
31+
validations:
32+
required: true
33+
34+
- type: textarea
35+
id: expected
36+
attributes:
37+
label: What did you expect?
38+
description: A clear description of what you expected to happen.
39+
validations:
40+
required: true
41+
42+
- type: textarea
43+
id: config
44+
attributes:
45+
label: Your model-fallback.json config (redact sensitive values)
46+
render: json
47+
48+
- type: textarea
49+
id: logs
50+
attributes:
51+
label: Relevant log output
52+
description: Paste any relevant lines from your log file (`~/.local/share/opencode/logs/`).
53+
render: text
54+
55+
- type: textarea
56+
id: repro
57+
attributes:
58+
label: Steps to reproduce
59+
placeholder: |
60+
1. Configure fallback chain with ...
61+
2. Send a message that triggers a rate limit
62+
3. Observe ...
63+
validations:
64+
required: true
65+
66+
- type: dropdown
67+
id: os
68+
attributes:
69+
label: Operating system
70+
options:
71+
- macOS
72+
- Linux
73+
- Windows
74+
- Other
75+
validations:
76+
required: true

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Feature Request
2+
description: Suggest a new feature or enhancement
3+
labels: ["enhancement"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Have an idea for improving opencode-model-fallback? We'd love to hear it.
9+
10+
- type: textarea
11+
id: problem
12+
attributes:
13+
label: What problem does this solve?
14+
description: Describe the problem or limitation you're running into.
15+
validations:
16+
required: true
17+
18+
- type: textarea
19+
id: solution
20+
attributes:
21+
label: Describe your proposed solution
22+
description: A clear description of what you want to happen.
23+
validations:
24+
required: true
25+
26+
- type: textarea
27+
id: alternatives
28+
attributes:
29+
label: Alternatives considered
30+
description: Any alternative solutions or workarounds you've considered.
31+
32+
- type: textarea
33+
id: context
34+
attributes:
35+
label: Additional context
36+
description: Any other context, screenshots, or examples.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
## Summary
2+
3+
<!-- A concise description of what this PR does and why. -->
4+
5+
## Changes
6+
7+
<!-- List the key changes made: -->
8+
9+
-
10+
-
11+
-
12+
13+
## Type of change
14+
15+
- [ ] Bug fix (non-breaking change that fixes an issue)
16+
- [ ] New feature (non-breaking change that adds functionality)
17+
- [ ] Breaking change (fix or feature that changes existing behavior)
18+
- [ ] Documentation update
19+
- [ ] Test improvement
20+
- [ ] Refactor / maintenance
21+
22+
## Testing
23+
24+
<!-- Describe how you tested the changes. -->
25+
26+
- [ ] `bun test` passes (all 101 tests)
27+
- [ ] `bunx tsc --noEmit` passes
28+
- [ ] `bun run lint` passes
29+
- [ ] `bun run build` succeeds
30+
31+
## Related issues
32+
33+
<!-- Link any related issues: Closes #, Fixes #, Relates to # -->
34+
35+
## Notes for reviewers
36+
37+
<!-- Anything specific you'd like reviewers to focus on. -->

‎CODE_OF_CONDUCT.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
6+
7+
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
8+
9+
## Our Standards
10+
11+
Examples of behavior that contributes to a positive environment for our community include:
12+
13+
- Demonstrating empathy and kindness toward other people
14+
- Being respectful of differing opinions, viewpoints, and experiences
15+
- Giving and gracefully accepting constructive feedback
16+
- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
17+
- Focusing on what is best not just for us as individuals, but for the overall community
18+
19+
Examples of unacceptable behavior include:
20+
21+
- The use of sexualized language or imagery, and sexual attention or advances of any kind
22+
- Trolling, insulting or derogatory comments, and personal or political attacks
23+
- Public or private harassment
24+
- Publishing others' private information, such as a physical or email address, without their explicit permission
25+
- Other conduct which could reasonably be considered inappropriate in a professional setting
26+
27+
## Enforcement Responsibilities
28+
29+
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
30+
31+
Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
32+
33+
## Scope
34+
35+
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
36+
37+
## Enforcement
38+
39+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at blazej@smartcoders.xyz. All complaints will be reviewed and investigated promptly and fairly.
40+
41+
All community leaders are obligated to respect the privacy and security of the reporter of any incident.
42+
43+
## Enforcement Guidelines
44+
45+
Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
46+
47+
### 1. Correction
48+
49+
**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
50+
51+
**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
52+
53+
### 2. Warning
54+
55+
**Community Impact**: A violation through a single incident or series of actions.
56+
57+
**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
58+
59+
### 3. Temporary Ban
60+
61+
**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
62+
63+
**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
64+
65+
### 4. Permanent Ban
66+
67+
**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
68+
69+
**Consequence**: A permanent ban from any sort of public interaction within the community.
70+
71+
## Attribution
72+
73+
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
74+
75+
Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
76+
77+
For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

‎CONTRIBUTING.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Contributing to opencode-model-fallback
2+
3+
Thank you for your interest in contributing! This document outlines the process for contributing to this project.
4+
5+
## Getting Started
6+
7+
```bash
8+
# Clone the repo
9+
git clone https://github.com/Smart-Coders-HQ/opencode-model-fallback.git
10+
cd opencode-model-fallback
11+
12+
# Install dependencies
13+
bun install
14+
15+
# Run tests
16+
bun test
17+
18+
# Type check
19+
bunx tsc --noEmit
20+
21+
# Build
22+
bun run build
23+
```
24+
25+
## Development Workflow
26+
27+
1. **Fork** the repository and create a feature branch from `main`.
28+
2. **Write code** — follow the [TypeScript/JavaScript conventions](https://github.com/Smart-Coders-HQ/opencode-model-fallback/blob/main/AGENTS.md) in `AGENTS.md`.
29+
3. **Test** — add tests for new functionality. All tests must pass: `bun test`.
30+
4. **Lint** — run `bun run lint` and `bun run format` before committing.
31+
5. **Commit** — use [Conventional Commits](https://www.conventionalcommits.org/) format:
32+
- `feat: add X` — new feature (triggers minor release)
33+
- `fix: correct Y` — bug fix (triggers patch release)
34+
- `docs: update Z` — documentation only
35+
- `test: add coverage for W` — test changes
36+
- `chore: bump deps` — maintenance
37+
- `BREAKING CHANGE:` in footer — triggers major release
38+
6. **Pull Request** — open a PR against `main`. Fill in the PR template.
39+
40+
## Quality Gates
41+
42+
Before a PR can be merged, all of these must pass:
43+
44+
- `bun run lint` — Biome linting
45+
- `bun test` — 101 tests, 0 failures
46+
- `bunx tsc --noEmit` — TypeScript type check
47+
- `bun run build` — clean build
48+
49+
## Architecture
50+
51+
The plugin is structured as follows:
52+
53+
```
54+
src/
55+
plugin.ts # Entry point — event router + chat.message hook
56+
preemptive.ts # Sync preemptive redirect logic
57+
types.ts # Shared type definitions
58+
config/ # Zod schema, file discovery, defaults, auto-migration
59+
detection/ # Pattern matching + error classification
60+
state/ # ModelHealthStore, SessionStateStore, FallbackStore
61+
resolution/ # Chain walker, agent→config resolver
62+
replay/ # abort→revert→prompt orchestrator
63+
display/ # Toast notifications, usage enrichment
64+
tools/ # /fallback-status tool
65+
logging/ # Structured file + client logger
66+
```
67+
68+
See `AGENTS.md` for full architecture details and key invariants.
69+
70+
## Reporting Issues
71+
72+
Please use [GitHub Issues](https://github.com/Smart-Coders-HQ/opencode-model-fallback/issues) and select the appropriate template.
73+
74+
## Security Vulnerabilities
75+
76+
Please do **not** open public issues for security vulnerabilities. See [SECURITY.md](SECURITY.md) for responsible disclosure instructions.
77+
78+
## License
79+
80+
By contributing, you agree that your contributions will be licensed under the [Apache 2.0 License](LICENSE).

‎SECURITY.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Security Policy
2+
3+
## Supported Versions
4+
5+
| Version | Supported |
6+
| ------- | ------------------ |
7+
| 0.1.x | :white_check_mark: |
8+
9+
## Reporting a Vulnerability
10+
11+
**Please do not report security vulnerabilities through public GitHub issues.**
12+
13+
To report a security vulnerability, email us at **blazej@smartcoders.xyz** with the subject line `[SECURITY] opencode-model-fallback`.
14+
15+
Please include:
16+
17+
- A description of the vulnerability and its potential impact
18+
- Steps to reproduce the issue
19+
- Any suggested mitigations or fixes
20+
21+
You should receive a response within **72 hours**. If you do not hear back, please follow up via email.
22+
23+
We will:
24+
25+
1. Acknowledge receipt of your report
26+
2. Investigate and confirm the vulnerability
27+
3. Work on a fix and release a patched version
28+
4. Credit you in the release notes (unless you prefer to remain anonymous)
29+
30+
## Scope
31+
32+
This security policy covers the `opencode-model-fallback` plugin code. It does not cover:
33+
34+
- Third-party dependencies (report those to the respective projects)
35+
- The OpenCode runtime itself
36+
- Issues requiring physical access to your machine
37+
38+
## Known Security Considerations
39+
40+
- **Config file permissions**: The plugin reads config from `~/.config/opencode/model-fallback.json` and agent config directories. Ensure these paths have appropriate permissions (readable only by your user).
41+
- **Log files**: Log files stored in `~/.local/share/opencode/logs/` may contain model usage metadata. They are created with `0o600` permissions (owner read/write only).
42+
- **YAML parsing**: Agent config files with YAML frontmatter are parsed with the CORE schema, which disallows executable YAML types.
43+
44+
Thank you for helping keep opencode-model-fallback secure.

0 commit comments

Comments
 (0)