From 9e3dd1db7f18b70666461c3a3f4c256b811cb44d Mon Sep 17 00:00:00 2001 From: can1357 Date: Fri, 19 Jun 2026 03:46:11 +0200 Subject: [PATCH] ci: added vouch-manage workflow and contribution guidelines - Added a GitHub Action workflow to manage user vouching through discussion comments. - Created CONTRIBUTING.md to define the vouching policy and workflow for contributors. - Updated README.md to include instructions on the required vouching process for pull requests. --- .github/workflows/vouch-manage.yml | 44 ++++++++++++++++++++++++ CONTRIBUTING.md | 54 ++++++++++++++++++++++++++++++ README.md | 9 +++++ 3 files changed, 107 insertions(+) create mode 100644 .github/workflows/vouch-manage.yml create mode 100644 CONTRIBUTING.md diff --git a/.github/workflows/vouch-manage.yml b/.github/workflows/vouch-manage.yml new file mode 100644 index 000000000..e7ce41b11 --- /dev/null +++ b/.github/workflows/vouch-manage.yml @@ -0,0 +1,44 @@ +name: Vouch (manage) + +# Let maintainers vouch/denounce/unvouch by commenting on a Discussion: +# !vouch vouch the discussion author +# !vouch @user [reason] vouch a specific user +# !denounce [@user] [reason] +# !unvouch [@user] +# Only collaborators with admin/maintain/write are honored (triage EXCLUDED; +# upstream's default `roles` includes triage, which we override below). +# +# Commits the VOUCHED.td change back to the default branch using the stock +# GITHUB_TOKEN (no GitHub App needed). NOTE: this works only while the default +# branch is UNPROTECTED — GITHUB_TOKEN cannot bypass branch protection. If you +# protect the branch later, switch back to a GitHub App token on a bypass list. + +on: + discussion_comment: + types: [created] + +# Serialize writes to VOUCHED.td so concurrent vouches don't clobber. +concurrency: + group: vouch-manage + cancel-in-progress: false + +permissions: + contents: write # commit VOUCHED.td + discussions: write # read the comment / acknowledge + +jobs: + manage: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: mitchellh/vouch/action/manage-by-discussion@v1 + with: + discussion-number: ${{ github.event.discussion.number }} + comment-node-id: ${{ github.event.comment.node_id }} + vouch-keyword: "!vouch" + denounce-keyword: "!denounce" + unvouch-keyword: "!unvouch" + roles: admin,maintain,write + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..66f25b399 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,54 @@ +# Contributing to oh-my-pi + +Thanks for your interest in contributing. This project uses a lightweight +**vouch** system to decide who can open pull requests. Please read this before +opening a PR. + +## TL;DR + +- **Issues are open to everyone.** File bugs, feature requests, and questions + freely — they are triaged automatically. +- **Pull requests require a vouch.** A PR whose author is not vouched (or is + denounced) is **closed automatically**. If you are not yet vouched, do **not** + open a PR to get noticed — it will be closed on sight. Start a Discussion and + ask to be vouched first (see below). + +## Who can open PRs + +A pull request is accepted when its author is any of: + +- a repository collaborator (write access or above), or a bot; or +- listed — without a leading `-` — in [`.github/VOUCHED.td`](.github/VOUCHED.td). + +Anyone **denounced** (prefixed with `-` in that file) is always blocked. + +## Getting vouched + +1. Open a [Discussion](../../discussions) (or comment on an existing one) + describing what you'd like to contribute. +2. A maintainer vouches you by commenting **`!vouch`** (vouches the discussion + author) or **`!vouch @your-handle`** on that discussion. +3. Once you appear in `.github/VOUCHED.td`, open your PR — it stays open and is + reviewed. + +Maintainers may also `!denounce [@user]` and `!unvouch [@user]`. Only +collaborators with admin/maintain/write can run these commands. + +## What happens to your PR + +| You are… | Result | +| --- | --- | +| Vouched (or a collaborator) | PR stays open → automated review → human review | +| Not vouched | PR closed with a comment — get vouched, then reopen or open a new PR | +| Denounced | PR closed | + +Pushing more commits to an open, vouched PR is fine — it remains vouched. + +## The VOUCHED.td file + +[`.github/VOUCHED.td`](.github/VOUCHED.td) is the source of truth: one handle per +line, sorted alphabetically, optionally `platform:handle`, with `-` marking a +denouncement and an optional reason after the handle. The format follows +[mitchellh/vouch](https://github.com/mitchellh/vouch); the denouncement list is +intentionally public so other projects can reuse our prior knowledge of bad +actors. diff --git a/README.md b/README.md index 823c14741..c129a182e 100644 --- a/README.md +++ b/README.md @@ -529,6 +529,15 @@ For architecture and contribution guidelines, see [packages/coding-agent/DEVELOP | **[brush-core-vendored](crates/brush-core-vendored)** | Vendored fork of [brush-shell](https://github.com/reubeno/brush) for embedded bash execution | | **[brush-builtins-vendored](crates/brush-builtins-vendored)** | Vendored bash builtins (cd, echo, test, printf, read, export, etc.) | +## Contributing + +Issues are open to everyone. **Pull requests require a vouch** — PRs from +unvouched or denounced authors are closed automatically. If you're not yet +vouched, open a [Discussion](https://github.com/can1357/oh-my-pi/discussions) +and ask a maintainer to `!vouch` you rather than opening a PR (which would be +closed on sight). See **[CONTRIBUTING.md](CONTRIBUTING.md)** and +[`.github/VOUCHED.td`](.github/VOUCHED.td) for the full policy. + --- ## License