mirror of
https://github.com/mvschwarz/openrig.git
synced 2026-11-07 05:56:21 -10:00
docs: add contributor guidance and community reporting routes
Add contribution, conduct, security, and support guidance plus bug, feature, and pull request templates. Set the project conduct contact and use the canonical documentation domain. Community drafts by the Planner agent; source, privacy, and final preparation corrections by the Guard agent. Co-authored-by: OpenRig agent (dev-planner) <[email protected]>
This commit is contained in:
OpenRig agent (dev-guard) committed
1 parent
b374dde300
commit
ae8cf9c8f2
8 files changed
+350
No files matched your search
@@ -0,0 +1,60 @@
|
||||
name: Bug report
|
||||
description: Something OpenRig does is wrong, or a command fails
|
||||
labels: ["bug"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thanks. Include a small reproduction and the relevant versions.
|
||||
This report will be public. Remove API keys, tokens, private prompts, personal details and private paths from commands, logs and configuration.
|
||||
For a suspected vulnerability, follow our [security policy](https://github.com/mvschwarz/openrig/security/policy) instead of posting details here.
|
||||
- type: input
|
||||
id: version
|
||||
attributes:
|
||||
label: OpenRig version
|
||||
description: Output of `rig --version`
|
||||
placeholder: 0.5.14 (2edc1b7a)
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
id: platform
|
||||
attributes:
|
||||
label: OS, Node and tmux versions
|
||||
placeholder: macOS 15.6, Node 22.22.1, tmux 3.5a
|
||||
validations:
|
||||
required: true
|
||||
- type: dropdown
|
||||
id: harness
|
||||
attributes:
|
||||
label: Harnesses involved
|
||||
multiple: true
|
||||
options:
|
||||
- None / not sure
|
||||
- Claude Code
|
||||
- Codex
|
||||
- Pi / Oh My Pi
|
||||
- Other (say which below)
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: repro
|
||||
attributes:
|
||||
label: What you ran and what happened
|
||||
description: The command(s), relevant redacted output, and what you expected instead. Paste text where you can; screenshots are useful for visual issues.
|
||||
render: shell
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: state
|
||||
attributes:
|
||||
label: Instance state that might matter
|
||||
description: Fresh install or upgrade? Include only relevant redacted lines from status output or your rig spec; do not upload full transcripts, credentials or your instance directory.
|
||||
- type: checkboxes
|
||||
id: checks
|
||||
attributes:
|
||||
label: Checks
|
||||
options:
|
||||
- label: I searched existing issues and Discussions for this.
|
||||
required: true
|
||||
- label: I am on the latest published version, or I said which version above.
|
||||
required: true
|
||||
@@ -0,0 +1,14 @@
|
||||
blank_issues_enabled: true
|
||||
contact_links:
|
||||
- name: Ask a question
|
||||
url: https://github.com/mvschwarz/openrig/discussions/categories/q-a
|
||||
about: Setup, usage and "is this expected" questions go to Discussions Q&A.
|
||||
- name: Share an idea or a setup
|
||||
url: https://github.com/mvschwarz/openrig/discussions
|
||||
about: Ideas and Show and tell live in Discussions.
|
||||
- name: Documentation
|
||||
url: https://openrig.dev/docs
|
||||
about: Getting started, CLI reference, configuration and troubleshooting.
|
||||
- name: Security report
|
||||
url: https://github.com/mvschwarz/openrig/security/policy
|
||||
about: Read how to arrange a private report. Do not include vulnerability details in public issues.
|
||||
@@ -0,0 +1,32 @@
|
||||
name: Feature request
|
||||
description: Something you want OpenRig to do that it does not
|
||||
labels: ["enhancement"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
For open-ended ideas or "how should this work" questions, [Discussions › Ideas](https://github.com/mvschwarz/openrig/discussions/categories/ideas) is the better place. Use this form when you can name the outcome you want.
|
||||
This request will be public; use examples without credentials, private prompts or personal details.
|
||||
- type: textarea
|
||||
id: outcome
|
||||
attributes:
|
||||
label: What are you trying to do, and what stops you today?
|
||||
description: Describe the situation, not the solution. One real example beats a general case.
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: proposal
|
||||
attributes:
|
||||
label: What would you like OpenRig to do?
|
||||
description: A command, a setting, a behaviour. Rough is fine.
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: workaround
|
||||
attributes:
|
||||
label: How do you handle it now?
|
||||
- type: input
|
||||
id: version
|
||||
attributes:
|
||||
label: OpenRig version
|
||||
placeholder: 0.5.14
|
||||
@@ -0,0 +1,17 @@
|
||||
<!-- Thanks for the PR. Three short answers are all a reviewer needs. -->
|
||||
|
||||
## What a user gets
|
||||
|
||||
<!-- One or two sentences: the behaviour before, the behaviour after. Link the issue if there is one. -->
|
||||
|
||||
## How you verified it
|
||||
|
||||
<!-- What you actually ran and saw, and which revision/local changes you tested. The documented checks are `npm run build`, `npm test`, and `npm run lint`; say what you could not run. Redact credentials and private information from logs or screenshots. -->
|
||||
|
||||
## Anything you were unsure about
|
||||
|
||||
<!-- Design choices, edge cases you did not cover, places a reviewer should look hardest. Empty is a fine answer. -->
|
||||
|
||||
- [ ] One concern per PR; no version bump; no `CHANGELOG.md` edit
|
||||
- [ ] Tests added or updated where the change is testable
|
||||
- [ ] I listed the checks I ran, their results, and any checks I could not run
|
||||
@@ -0,0 +1,16 @@
|
||||
# Getting help with OpenRig
|
||||
|
||||
- **Docs:** https://openrig.dev/docs — getting started, CLI reference, configuration,
|
||||
troubleshooting. An index linking to agent-friendly documentation is at
|
||||
https://openrig.dev/llms.txt.
|
||||
- **Questions:** [Discussions › Q&A](https://github.com/mvschwarz/openrig/discussions/categories/q-a).
|
||||
- **Bugs:** [open an issue](https://github.com/mvschwarz/openrig/issues/new/choose) with the bug
|
||||
template. Include `rig --version`, your OS and Node versions, and relevant redacted command output.
|
||||
Reports are public: remove credentials, private prompts and personal information.
|
||||
- **Ideas and setups:** [Ideas](https://github.com/mvschwarz/openrig/discussions/categories/ideas)
|
||||
and [Show and tell](https://github.com/mvschwarz/openrig/discussions/categories/show-and-tell).
|
||||
- **Videos:** https://www.youtube.com/@openrig
|
||||
- **Security:** see [SECURITY.md](../SECURITY.md); please report privately.
|
||||
|
||||
We aim to acknowledge issues and pull requests within one day. A substantive PR review decision
|
||||
within seven days is a target, not a guaranteed deadline. Details in [CONTRIBUTING.md](../CONTRIBUTING.md).
|
||||
@@ -0,0 +1,75 @@
|
||||
# Code of Conduct
|
||||
|
||||
## Our pledge
|
||||
|
||||
We as members, contributors, and maintainers pledge to make participation in OpenRig 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.
|
||||
|
||||
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive,
|
||||
and healthy community.
|
||||
|
||||
## Our standards
|
||||
|
||||
Examples of behaviour that contributes to a positive environment:
|
||||
|
||||
- Demonstrating empathy and kindness toward other people
|
||||
- Being respectful of differing opinions, viewpoints, and experiences
|
||||
- Giving and gracefully accepting constructive feedback
|
||||
- Accepting responsibility and apologizing to those affected by our mistakes, and learning from
|
||||
the experience
|
||||
- Focusing on what is best not just for us as individuals, but for the overall community
|
||||
|
||||
Examples of unacceptable behaviour:
|
||||
|
||||
- The use of sexualized language or imagery, and sexual attention or advances of any kind
|
||||
- Trolling, insulting or derogatory comments, and personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information, such as a physical or email address, without their
|
||||
explicit permission
|
||||
- Other conduct which could reasonably be considered inappropriate in a professional setting
|
||||
|
||||
## Enforcement responsibilities
|
||||
|
||||
Project maintainers are responsible for clarifying and enforcing our standards of acceptable
|
||||
behaviour and will take appropriate and fair corrective action in response to any behaviour that
|
||||
they deem inappropriate, threatening, offensive, or harmful. Maintainers have the right and
|
||||
responsibility to remove, edit, or reject comments, commits, code, issues, and other contributions
|
||||
that are not aligned to this Code of Conduct, and will communicate reasons for moderation
|
||||
decisions when appropriate.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies within all project spaces (the repository, Discussions, issues and
|
||||
pull requests) and when an individual is officially representing the project in public spaces.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported to the
|
||||
maintainers at **[email protected]**. All complaints will be reviewed and investigated
|
||||
promptly and fairly.
|
||||
All maintainers are obligated to respect the privacy and security of the reporter of any incident.
|
||||
|
||||
## Enforcement guidelines
|
||||
|
||||
Maintainers will follow these community impact guidelines in determining the consequences for any
|
||||
action they deem in violation of this Code of Conduct:
|
||||
|
||||
1. **Correction.** A private, written warning, with clarity around the nature of the violation and
|
||||
an explanation of why the behaviour was inappropriate. A public apology may be requested.
|
||||
2. **Warning.** A warning with consequences for continued behaviour, including no interaction with
|
||||
the people involved for a specified period.
|
||||
3. **Temporary ban.** A temporary ban from any sort of interaction or public communication with
|
||||
the community for a specified period.
|
||||
4. **Permanent ban.** A permanent ban from any sort of public interaction within the community.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
|
||||
version 2.1 by Coraline Ada Ehmke, available at
|
||||
https://www.contributor-covenant.org/version/2/1/code_of_conduct.html and licensed under
|
||||
[Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/).
|
||||
This adaptation names OpenRig and its maintainers and summarizes the enforcement guidelines. Community impact guidelines
|
||||
were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
|
||||
@@ -0,0 +1,89 @@
|
||||
# Contributing to OpenRig
|
||||
|
||||
Thanks for being here. OpenRig is built in the open and by the thing it is: a rig of coding
|
||||
agents and a small group of people. External pull requests and issues have started arriving
|
||||
faster than we planned for, which is the best problem to have. This page says how to get a
|
||||
change in with the least friction on both sides.
|
||||
|
||||
## Before you start
|
||||
|
||||
- **Bugs:** open an issue with the bug template. Include your OpenRig version (`rig --version`),
|
||||
OS, Node version, which harnesses are involved (or none), and the relevant command and output.
|
||||
Reports are public: remove credentials, private prompts, personal details and private paths
|
||||
before posting. Share a small reproduction rather than a full transcript or instance dump.
|
||||
- **Features and behaviour changes:** open an issue or a Discussion in *Ideas* first. A short
|
||||
"what I am trying to do and what stops me" saves both of us a rewrite. Small, obvious fixes do
|
||||
not need an issue.
|
||||
- **Questions:** use [Discussions › Q&A](https://github.com/mvschwarz/openrig/discussions/categories/q-a),
|
||||
not an issue.
|
||||
|
||||
## Setting up
|
||||
|
||||
Node `^20 || ^22 || ^24` and a working `tmux` are required. Then:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/mvschwarz/openrig.git
|
||||
cd openrig
|
||||
npm install
|
||||
npm run build # all workspaces
|
||||
npm test # repo checks + daemon, cli, tui test suites
|
||||
npm run lint # typecheck every package
|
||||
```
|
||||
|
||||
`npm test` builds the daemon and runs repository checks before the package suites. Read the
|
||||
specific failure: `npm run mirror-skills` updates skill mirrors, and
|
||||
`npm run generate-context-packs` updates generated packs. Use them when their source changed and
|
||||
review the generated diff; neither command fixes every documentation failure. The UI unit-test
|
||||
suite is advisory and separate: `npm run test:ui`.
|
||||
|
||||
For hands-on development, read the [check requirements](docs/reference/developing.md),
|
||||
[worktree setup](docs/reference/worktree-builds.md), and
|
||||
[machine changes](README.md#what-openrig-changes-on-your-machine). Use an isolated environment
|
||||
for changes that start daemons or agents; `OPENRIG_HOME` alone does not isolate provider settings.
|
||||
Permission configuration is an [explicit choice](docs/reference/getting-started.md#have-your-agent-configure-permissions).
|
||||
A checked-out tree is not the installed daemon; restarting an installed daemon does not adopt
|
||||
your working copy.
|
||||
|
||||
## Making the change
|
||||
|
||||
- One concern per pull request. Keep unrelated refactors separate; explain any refactor needed
|
||||
for the fix.
|
||||
- Keep the diff small enough to review in one sitting. If it is not, say why in the description.
|
||||
- Add or update a test where the change is testable. Use focused deterministic tests where
|
||||
possible. For terminal or provider behaviour, state what was exercised with the actual runtime
|
||||
and what was simulated; a stub alone does not prove the native interaction works.
|
||||
- Do not edit `CHANGELOG.md`. Maintainers write release notes at the tag.
|
||||
- Do not bump versions.
|
||||
- Match the surrounding style. `npm run lint` typechecks; it does not format code.
|
||||
- Write commit messages in the form the log already uses: `fix(cli): …`, `feat(daemon): …`,
|
||||
`docs(reference): …`, `harness: …`.
|
||||
|
||||
## The pull request
|
||||
|
||||
Fill in the template. The three things a reviewer needs are: what a user gets, how you verified
|
||||
it, and anything you were unsure about. State the revision and relevant local changes you tested,
|
||||
what you actually ran, and any checks you could not run. Redact private information from evidence.
|
||||
|
||||
Contributions follow the repository's [Apache-2.0 license](LICENSE). Preserve attribution and any
|
||||
applicable license notices when adapting third-party material.
|
||||
|
||||
## What to expect from us
|
||||
|
||||
- We aim to acknowledge issues and pull requests within **one day**. An acknowledgement is not
|
||||
a completed review or a merge decision.
|
||||
- Our target for a first substantive review decision on an external PR is **seven days**. If it
|
||||
takes longer, we explain what is pending on the PR. This is a target, not a guaranteed deadline.
|
||||
- Labels you will see: `needs-repro` (we could not reproduce it yet; waiting on versions or steps),
|
||||
`fixed-on-main` (merged, not yet on npm), `good first issue`, `help wanted`, `discussion`
|
||||
(direction question; continues in Discussions).
|
||||
|
||||
Reviews here are done by people and by the project's own agents. An agent may ask the first
|
||||
clarifying question or run the reproduction; a maintainer makes the merge decision.
|
||||
|
||||
## Where things live
|
||||
|
||||
- Repository reference: `docs/reference/`; user documentation: [openrig.dev/docs](https://openrig.dev/docs).
|
||||
- Skills: `packages/daemon/specs/agents/shared/skills/` and plugin skills under
|
||||
`packages/daemon/assets/plugins/`; static context-pack sources: `packages/daemon/context-packs-src/`.
|
||||
Generated packs live in `packages/daemon/context-packs/` and are not hand-edited or committed.
|
||||
- Releases: [GitHub Releases](https://github.com/mvschwarz/openrig/releases) and npm `@openrig/cli`.
|
||||
+47
@@ -0,0 +1,47 @@
|
||||
# Security policy
|
||||
|
||||
## Supported versions
|
||||
|
||||
Only the latest published version on npm (`@openrig/cli`) is supported. Fixes are developed on
|
||||
`main` and released after verification; a merged fix is not necessarily in the published package.
|
||||
Include the affected version even when reporting a problem in an older installation.
|
||||
|
||||
## What OpenRig touches
|
||||
|
||||
OpenRig runs a local daemon, drives coding agents in tmux sessions on your machine, and writes
|
||||
configuration for those harnesses (for example under `~/.claude` and `~/.codex`). The README
|
||||
section [What OpenRig changes on your machine](README.md#what-openrig-changes-on-your-machine)
|
||||
describes these effects and the trust/permission choices. Unexpected access, disclosure or
|
||||
permission changes are useful reports; include what you expected and what you observed.
|
||||
|
||||
## Reporting a vulnerability
|
||||
|
||||
Please do not open a public issue for a vulnerability.
|
||||
|
||||
Open the repository's [Security page](https://github.com/mvschwarz/openrig/security). If
|
||||
**Report a vulnerability** is available, use it to send a private report to the maintainers.
|
||||
The reporter and authorized advisory collaborators can also see that report; it is not public.
|
||||
Availability depends on the repository setting, not on this file being present.
|
||||
|
||||
If that option is unavailable, ask in [Discussions Q&A](https://github.com/mvschwarz/openrig/discussions/categories/q-a)
|
||||
for a private security contact. Post only the request for a channel: do not include the
|
||||
vulnerability details, reproduction, logs, credentials or affected private systems in public.
|
||||
Wait for the private channel before sharing the report.
|
||||
|
||||
Include: the OpenRig version, the harnesses involved, the steps to reproduce, and what an attacker
|
||||
could do. A proof of concept is welcome; a working exploit against a third party's machine is not.
|
||||
|
||||
## What to expect
|
||||
|
||||
- We will acknowledge the report and coordinate assessment and next steps privately.
|
||||
- Assessment and fix timing depend on impact and reproduction; no fixed deadline is promised.
|
||||
- We will agree on disclosure and credit with you. You can ask to remain anonymous.
|
||||
|
||||
## Scope notes
|
||||
|
||||
- OpenRig assumes the machine and the accounts it runs under are trusted by their owner. Reports
|
||||
that require a hostile local user with the same account are still welcome but are unlikely to be
|
||||
treated as high severity.
|
||||
- A harness carrying out an intentionally authorized operation is not by itself evidence of an
|
||||
OpenRig vulnerability. Reports of OpenRig bypassing a chosen permission, changing trust
|
||||
unexpectedly, or routing data or actions to the wrong destination are in scope.
|
||||
Reference in new issue
Block a user