Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.
JavaScript agentic-codingai-agentsai-governanceautonomous-agentsclaude-codeclicode-reviewcodexcoding-agentsdeveloper-toolsgit-hooksllmlocal-firstmulti-agentsoftware-factoryspec-driven-developmentverificationvibe-coding
docs(contributing): clarify CLA and assert each step [I11]
Corey Olsonfd391db50ccc
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdindex b50d7467..9c7df2a7 100644--- a/.github/pull_request_template.md+++ b/.github/pull_request_template.md@@ -1,5 +1,15 @@## What changed?+## Linked issue++Fixes #+## Which approved spec rows does this serve?## How was it proven?++## Contribution checks++- [ ] I have signed off every commit (`git commit -s`; see [How to sign off](../CONTRIBUTING.md#how-to-sign-off-step-by-step)).++On your first pull request, agree to the [CLA](../CLA.md) through the CLA bot. Both the CLA agreement and a sign-off on every commit are required before merge.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex d78627d1..435157a0 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -1,3 +1,118 @@# Contributing-Issues are welcome. Pull requests must be serious contributions. All contributions are licensed under MIT.+Thanks for helping. Pullboard is MIT-licensed.++## The short version++- **Issues are always welcome:** bugs, ideas and questions.+- **Pull requests are welcome too.** Every one goes through the same checks as the work Pullboard's own agents do, and nothing skips them.+- **Two quick steps for your first pull request:** agree to our Contributor License Agreement (one click, once) and sign off each commit (one flag). Both are explained below.++## Licensing, the CLA and sign-off++**The Contributor License Agreement (CLA).** The first time you open a pull request, a bot asks you to agree to Pullboard's CLA with one click. You only do this once. In short:++- **You keep ownership** of your contribution.+- You give the Pullboard project a broad, permanent license to use, change and distribute it, including under other licenses in the future, plus a license to any patents of yours that your contribution needs.+- You confirm it's your own work, or that you have permission to contribute it.++Read the full text before agreeing: [CLA.md](CLA.md). It follows the Apache Individual Contributor License Agreement v2.2 terms, with Pullboard as recipient; the nonprofit-bylaws sentence and form fields are omitted, and acceptance is through the CLA bot.++**The sign-off.** Each commit also carries a sign-off line confirming you have the right to submit it, as described in the [Developer Certificate of Origin 1.1](https://developercertificate.org/). `git commit -s` adds it for you:++```+Signed-off-by: Your Name <[email protected]>+```++A pull request can't be merged until the CLA is agreed and every commit is signed off.++Pullboard itself stays available to everyone under the MIT License. The CLA covers only what you contribute, and puts no conditions on people who use Pullboard.++### How to sign off, step by step++The sign-off is one line at the bottom of each commit message. Git writes it for you, using the name and email from your git settings.++**A new commit:** add `-s` when you commit.++```bash+git commit -s -m "fix(relay): finish pending reads before yielding"+```++The commit message now ends with:++```+Signed-off-by: Your Name <[email protected]>+```++**A commit you already made but haven't pushed:** add the line to your latest commit.++```bash+git commit --amend -s --no-edit+```++**A pull request you already opened.** Run these in your copy of the repository, on the branch the pull request comes from.++1. Add the sign-off to every commit on your branch (replace `main` if your branch started from something else):++ ```bash+ git rebase --signoff main+ ```++ With only one commit, `git commit --amend -s --no-edit` does the same.++2. Push the updated commits to your pull request:++ ```bash+ git push --force-with-lease+ ```++ This replaces the commits on your own branch only; nothing else is affected. Your pull request updates by itself within a few seconds.++3. Check it: open the pull request's **Commits** tab, click a commit, and confirm its message ends with your `Signed-off-by:` line.++**Editing on github.com instead of on your computer:** type the line yourself at the bottom of the commit message box, exactly like this, with your name and the email on your GitHub account:++```+Signed-off-by: Your Name <[email protected]>+```++**Sign off every commit automatically:** this creates a shortcut, `git cs`, for "commit with sign-off".++```bash+git config --global alias.cs "commit -s"+```++Then use `git cs -m "..."` instead of `git commit -m "..."`.++## What makes a good contribution++- **Start with an issue** for anything beyond a small fix, so we can agree on the behaviour first. Pullboard's requirements live in `SPEC.md`, and the project owner approves changes to them.+- **Bug fixes:** link the issue, and include a test that fails without your fix and passes with it.+- **Code:** plain JavaScript, ES modules, Node 22.13 or newer, and no new dependencies. Match the surrounding style. Run `npm run gate` before you open the pull request.+- **AI-assisted work is fine.** You're responsible for it, and it meets the same bar as everything else.++## What happens after you open a pull request++1. **We look at it when we can.** There is no fixed response time, and we may not reply to every pull request.+2. **It becomes an item on Pullboard's own board.** The bar is the behaviour your issue describes.+3. **A second reviewer checks your exact commit.** That's one of our verifier agents, plus the project owner for sensitive areas. It runs the full test suite on the minimum Node version and confirms your test fails without your change.+4. **If it passes,** it lands on `main` through our normal landing process, with you credited as the author. If we had to adjust it, you're credited as co-author with `Co-authored-by`. The pull request shows as merged, or we close it with a link to where it landed.+5. **If it doesn't pass,** we comment with what failed, and you can update the pull request.++We may edit, combine or reimplement a contribution, and we may decline one with a reason. Merging is always the project's call.++## Sensitive areas++Changes to these also need the project owner's approval:+- the relay and board sealing;+- signing and keys;+- person-only moves (approvals, sign-offs);+- git hooks and the verification rules.++## Security issues++Don't open a public issue or pull request for a vulnerability. Report it privately through this repository's Security tab (see `SECURITY.md`).++## Conduct++Everyone here follows our [Code of Conduct](CODE_OF_CONDUCT.md).diff --git a/docs/contributing-runbook.md b/docs/contributing-runbook.mdnew file mode 100644index 00000000..c0f52ce5--- /dev/null+++ b/docs/contributing-runbook.md@@ -0,0 +1,47 @@+# Procedure: handling an outside contribution (maintainers and the coordinator)++Approved direction from the person, 22 Oct 2026. This is the internal runbook. Contributors read CONTRIBUTING.md; this file is for us.++## When an issue arrives+1. Reply when capacity allows: thank them, and say what happens next ("on our board as #N", "a question first", or "not planned, because...").+2. File it on the board, or map it onto an existing item or milestone. Link the board item in the reply.++## When a pull request arrives+1. **Reply when capacity allows; there is no fixed response time.** Thank them, and ask for a sign-off if any commit lacks one (point at CONTRIBUTING, "How to sign off").+2. **Read the diff before running anything.** Look for:+ - changes outside the stated purpose;+ - new dependencies (refuse them);+ - anything touching sensitive paths (relay, sealing, signing, person moves, hooks, code that runs commands);+ - network calls, file access outside the repo, obfuscation, big pasted blocks.+3. **File it as a board item.** The bar is the linked issue's behaviour. The check is the contributor's new test, which must fail on `main` and pass at their commit. Record the PR number, the author and the exact commit.+4. **Verify in the sandbox only:**+ - a container or throwaway VM with no credentials, no access to the home folder and no network;+ - the full gate on the minimum Node version (22.13) plus the current version;+ - the browser tests when the change touches the view or relay;+ - outside code never runs on a machine holding credentials.+5. **Sensitive paths need the owner's approval** on top of the verifier's accept.+6. **Confirm the [CLA](../CLA.md) before merge:** the contributor accepts it through the CLA bot on their first pull request. **Then land through the merge train.** Never use GitHub's merge button. The contributor stays the commit author; if we changed their commit, they're credited with `Co-authored-by`. Keep their `Signed-off-by` line.+7. **Close the loop.** The PR shows as merged, or we close it with a link to the landed commit. Thank them, and link the receipt.+8. **If it fails,** comment with the verifier's note in plain words ("fails on Node 22.13: ..."). When they update, the item is verified again at the new commit.+9. **Declining:** close with a clear, kind reason. Merging is always the project's call.++## Standing rules+- Outsiders never get commit rights, npm publishing rights or any token.+- GitHub and npm accounts use 2FA. Releases are published only by the owner's release process.+- `main` is protected: only the coordinator's landing updates it.+- CODEOWNERS requests the owner's review on sensitive paths.+- Inbound contributions are MIT, with the DCO sign-off and a lightweight one-click CLA (decided 22 Oct). Make no public promise about future licensing.++## Automation to build (so this runs without anyone remembering it)+- **Sign-off check** in the commit-msg hook and CI for outside commits, with a message naming the fix.+- **`pullboard intake <PR>`** (the first real use of the PR bridge):+ - fetches the PR's exact commit;+ - files the item with the PR and author recorded;+ - marks it outside, so verification runs only in the sandbox;+ - routes it to the owner when it touches a sensitive path;+ - posts the result back to the PR with the receipt (after the owner's OK while we start).++ Any project using Pullboard then gets the same safe contribution flow.+- **A sandboxed verify mode** for items marked outside.+- **PR template** with a sign-off checkbox and a linked-issue field.+- **A reply reminder:** keep unanswered issues and pull requests visible without promising a response time.diff --git a/docs/contributing.test.js b/docs/contributing.test.jsnew file mode 100644index 00000000..ecb9bc9a--- /dev/null+++ b/docs/contributing.test.js@@ -0,0 +1,66 @@+/** @pullboard-test-input source-tree */+/** The approved contribution wording and the maintainers' complete safe intake path [I11]. */+import assert from 'node:assert/strict';+import { createHash } from 'node:crypto';+import { readFileSync } from 'node:fs';+import { test } from 'node:test';++/** Read a public contribution document from the checked source tree. */+const read = path => readFileSync(new URL('../' + path, import.meta.url), 'utf8');++test('CONTRIBUTING teaches the sign-off and the runbook names every step [I11]', () => {+ const contributing = read('CONTRIBUTING.md');+ assert.match(contributing, /How to sign off/u);+ assert.equal(createHash('sha256').update(contributing).digest('hex'),+ '75ea0c986e0a3e8d2dc9f1affcafcce4896e67500cbd6d5509e6663a2b784177',+ 'the approved contributor guide, including the accurate CLA description, is preserved');+ for (const phrase of ['git commit -s', 'git commit --amend -s --no-edit', 'git rebase --signoff main',+ 'Contributor License Agreement', 'You keep ownership', 'patents', 'no fixed response time']) {+ assert.ok(contributing.includes(phrase), phrase);+ }+ for (const phrase of ['Apache Individual Contributor License Agreement v2.2 terms', 'Pullboard as recipient',+ 'nonprofit-bylaws sentence and form fields are omitted', 'acceptance is through the CLA bot']) {+ assert.ok(contributing.includes(phrase), phrase);+ }+ const runbook = read('docs/contributing-runbook.md');+ for (const phrase of [+ 'When an issue arrives',+ 'Reply when capacity allows: thank them, and say what happens next',+ 'on our board as #N', 'a question first', 'not planned, because',+ 'File it on the board, or map it onto an existing item or milestone', 'Link the board item in the reply',+ 'When a pull request arrives',+ 'there is no fixed response time', 'ask for a sign-off if any commit lacks one', 'How to sign off',+ 'Read the diff before running anything', 'changes outside the stated purpose', 'new dependencies (refuse them)',+ 'sensitive paths (relay, sealing, signing, person moves, hooks, code that runs commands)',+ 'network calls, file access outside the repo, obfuscation, big pasted blocks',+ 'The check is the contributor\'s new test, which must fail on `main` and pass at their commit',+ 'Record the PR number, the author and the exact commit',+ 'a container or throwaway VM with no credentials, no access to the home folder and no network',+ 'the full gate on the minimum Node version (22.13) plus the current version',+ 'the browser tests when the change touches the view or relay',+ 'outside code never runs on a machine holding credentials',+ 'Sensitive paths need the owner\'s approval',+ 'Confirm the [CLA](../CLA.md) before merge', 'through the CLA bot on their first pull request',+ 'land through the merge train', 'Never use GitHub\'s merge button',+ 'The contributor stays the commit author', 'Co-authored-by', 'Keep their `Signed-off-by` line',+ 'The PR shows as merged, or we close it with a link to the landed commit', 'Thank them, and link the receipt',+ 'comment with the verifier\'s note in plain words', 'the item is verified again at the new commit',+ 'Declining:** close with a clear, kind reason', 'Merging is always the project\'s call',+ ]) {+ assert.ok(runbook.includes(phrase), phrase);+ }+ assert.doesNotMatch(runbook, /reply within 3 days/iu);+ const template = read('.github/pull_request_template.md');+ assert.match(template, /- \[ \].*sign.*off/iu);+ assert.match(template, /CLA/u);+ assert.match(template, /(?:linked.issue|fixes #)/iu);+ const cla = read('CLA.md');+ assert.match(cla, /\bversion 2\.2\b/u);+ assert.equal(createHash('sha256').update(cla).digest('hex'),+ '866fe77a4eb04eb948c5f92494804136ecce3980bc3e6280d7e638f0791a691c',+ 'the coordinator-approved 0124 CLA companion is copied without changing its terms');+ for (const phrase of ['Pullboard', 'Grant of Copyright License', 'Grant of Patent License',+ 'You reserve all right', 'WITHOUT WARRANTIES']) assert.ok(cla.includes(phrase), phrase);+ assert.ok(!cla.includes('[email protected]'), 'the Apache recipient is not presented as Pullboard contact');+ for (const path of ['SECURITY.md', 'CODE_OF_CONDUCT.md']) assert.ok(read(path).trim(), path);+});