From 9dc703b04d024506f67593b1990c4b0c6dbda1db Mon Sep 17 00:00:00 2001 From: derberg Date: Mon, 1 Jun 2026 23:21:55 +0200 Subject: [PATCH 1/5] docs: add AI usage policy for contributors --- .github/pull-request-template.md | 9 +- .github/workflows/verify-ai-disclosure.yml | 99 ++++++++++++++++++++++ AI-POLICY.md | 57 +++++++++++++ CONTRIBUTING.md | 9 ++ README.md | 2 + 5 files changed, 175 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/verify-ai-disclosure.yml create mode 100644 AI-POLICY.md diff --git a/.github/pull-request-template.md b/.github/pull-request-template.md index d1b83ed2c7..766c709660 100644 --- a/.github/pull-request-template.md +++ b/.github/pull-request-template.md @@ -12,4 +12,11 @@ **Related issue(s)** \ No newline at end of file +For example, `Resolves #123`, `Fixes #43`, or `See also #33`. The 3rd option will not automatically close the issue after the merge. --> + +**AI assistance** + + +- [ ] This PR was created with AI assistance — `Generated-by:` +- [ ] No AI assistance was used \ No newline at end of file diff --git a/.github/workflows/verify-ai-disclosure.yml b/.github/workflows/verify-ai-disclosure.yml new file mode 100644 index 0000000000..ec4c148c6a --- /dev/null +++ b/.github/workflows/verify-ai-disclosure.yml @@ -0,0 +1,99 @@ +# Purpose of this workflow is to enforce the AI Usage Policy (AI-POLICY.md): +# every pull request must declare whether it was AI-assisted, either by providing +# a non-empty `Generated-by:` line or by checking the "No AI assistance" box. +# This verifies that a declaration is PRESENT - it cannot verify its truthfulness. +# +# Why pull_request_target instead of pull_request: the check must be able to post a +# comment on pull requests opened from forks, and the plain `pull_request` event only +# grants a read-only token for forks. +# +# Security: this is hardened against the classic PR-body script-injection vector. +# - No `${{ }}` expression interpolation: the body is read at runtime as a JS value +# via context.payload.pull_request.body, never substituted into code. +# - The body is treated purely as data (regex/string ops); never eval'd, shelled, +# or passed to a `run:` step. +# - pull_request_target is safe because there is NO checkout - PR code is never +# fetched or executed, so the write-scoped token is never exposed to it. +# - The failure comment is static text and does not echo back the PR body. +# - Token is scoped to `pull-requests: write` only. +name: Verify AI disclosure + +on: + pull_request_target: + types: + - opened + - edited + - reopened + - synchronize + +permissions: + pull-requests: write + +jobs: + verify-ai-disclosure: + runs-on: ubuntu-latest + steps: + - name: Check PR body for AI-assistance disclosure + uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0 + with: + script: | + const MARKER = ''; + const policyUrl = 'https://github.com/asyncapi/generator/blob/master/AI-POLICY.md'; + const body = context.payload.pull_request.body || ''; + // Strip HTML comments so example text inside doesn't count as a real declaration. + const stripped = body.replace(//g, ''); + + const noAiChecked = /- \[x\]\s*No AI assistance/i.test(stripped); + + // Match only horizontal whitespace after the colon so an empty + // `Generated-by:` line does not swallow the following line as its value. + const values = [...stripped.matchAll(/Generated-by:[ \t]*([^\n]*)/gi)] + .map(m => m[1].replace(/`/g, '').trim()) + .filter(v => v.length > 0); + const generatedByValue = values[0] || ''; + const hasGeneratedBy = values.length > 0; + + const { owner, repo } = context.repo; + const issue_number = context.payload.pull_request.number; + + // Find a previous comment from this check so we update/remove it instead of spamming. + const comments = await github.paginate(github.rest.issues.listComments, { + owner, repo, issue_number, per_page: 100, + }); + const existing = comments.find(c => (c.body || '').includes(MARKER)); + + if (noAiChecked || hasGeneratedBy) { + core.info( + hasGeneratedBy + ? `AI assistance disclosed: Generated-by: ${generatedByValue}` + : 'Declared: no AI assistance used.' + ); + // PR is now compliant - clean up any earlier failure comment. + if (existing) { + await github.rest.issues.deleteComment({ owner, repo, comment_id: existing.id }); + } + return; + } + + const message = [ + MARKER, + '### ⚠️ Missing AI-assistance disclosure', + '', + `Per our [AI Usage Policy](${policyUrl}), every pull request must declare whether generative AI assisted in creating it. Please **edit this PR description** to do one of the following:`, + '', + '- If AI assisted, add a line naming the tool and version, for example:', + ' ```', + ' Generated-by: Claude Code 1.x', + ' ```', + '- If no AI was used, check the **"No AI assistance was used"** box in the PR template.', + '', + 'This check re-runs whenever you edit the description, and this comment will disappear once a declaration is present. Note that it confirms a declaration *exists* — it does not verify its accuracy; you remain accountable for everything you submit.', + ].join('\n'); + + if (existing) { + await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body: message }); + } else { + await github.rest.issues.createComment({ owner, repo, issue_number, body: message }); + } + + core.setFailed(`Missing AI-assistance disclosure. See ${policyUrl}`); diff --git a/AI-POLICY.md b/AI-POLICY.md new file mode 100644 index 0000000000..c7d19acecc --- /dev/null +++ b/AI-POLICY.md @@ -0,0 +1,57 @@ +# AI Usage Policy + +This policy governs the use of generative AI and AI-assisted tooling (LLMs, coding agents, autocomplete assistants, and similar) when contributing to this repository. + +> **AI tools are instruments; humans are the only authors.** + +You may use AI tools to help you contribute. But the moment you open a pull request or an issue, **you** are the author of every line in it. The tool is not a co-maintainer, it is not accountable, and it cannot be cited as an excuse. This policy exists so that AI accelerates good contributions without lowering the bar for quality, security, or trust. + +This is a contributor-facing policy. It is **not** the same as [`AGENTS.md`](AGENTS.md): that file instructs coding agents on *how to write code that fits this repository*, whereas this policy defines *the rules and expectations for humans who use AI to contribute here*. + +## When this applies + +This policy applies to **any** contribution where a generative AI tool materially assisted in producing the content, including: + +- source code, tests, and configuration, +- documentation and template content, +- issue descriptions, and +- review comments. + +If you only used AI for spell-checking, search, or to understand existing code, disclosure is not required. If AI generated or substantially shaped the content you are submitting, it is. + +## Your responsibilities as a contributor + +Before you submit AI-assisted work, you must: + +1. **Review it thoroughly.** Read and understand every part of the contribution. If you do not understand it, do not submit it. +2. **Verify quality.** Ensure it meets this project's standards — it builds, tests pass, and it follows the conventions in [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`AGENTS.md`](AGENTS.md). +3. **Remove extraneous changes.** Strip out unrelated edits, dead code, speculative abstractions, and noise the tool introduced. Keep the diff focused. +4. **Be prepared to explain it.** You must be able to justify any part of the contribution if a maintainer asks. "The AI wrote it" is not an answer. +5. **Accept responsibility.** You bear full accountability for the contribution, exactly as if you had written every line by hand. +6. **Check licensing.** Confirm that generated material does not reproduce code under incompatible licenses and does not violate this project's [license](LICENSE). + +> Blindly copy-pasting AI output introduces security and stability risks. Maintainers may close such pull requests without review. + +## Required disclosure + +If a contribution was materially AI-assisted, you **must** disclose it: + +- **Pull requests:** include a `Generated-by:` line in the PR description naming the tool and its version, for example: + + ``` + Generated-by: Claude Code 1.x + Generated-by: GitHub Copilot + ``` + + The pull request template carries a dedicated AI-assistance section — fill in the `Generated-by:` line, or check the "no AI assistance" box if it does not apply. A CI check verifies that one of the two is present; it confirms a declaration exists, it does not and cannot verify its truthfulness. + +- **Issues:** note in the issue body that AI assisted in drafting it. + +Disclosure is a sign of good faith, not an admission of wrongdoing. We welcome AI-assisted contributions that follow this policy. + +## Consequences + +- Maintainers may **close non-compliant pull requests without review**, including undisclosed AI-generated PRs and PRs the contributor cannot explain. +- **Repeated violations** are treated as a breach of our [Code of Conduct](CODE_OF_CONDUCT.md) and may result in the contributor being blocked. + +If you are unsure whether something falls under this policy, ask a maintainer in the `#generator` channel on [AsyncAPI Slack](https://www.asyncapi.com/slack-invite) before submitting. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d0220be0b9..96657f53a6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,6 +13,7 @@ We love your input! We want to make contributing to this project as easy and tra - [Issues](#issues) - [Bug Reports and Feature Requests](#bug-reports-and-feature-requests) - [Pull Requests](#pull-requests) +- [AI-Assisted Contributions](#ai-assisted-contributions) - [Conventional Commits](#conventional-commits) - [Maintainer Roles](#maintainer-roles) - [Triager](#triager) @@ -105,6 +106,14 @@ Please use our issues templates that provide you with hints on what information **Please, make sure you open an issue before starting with a Pull Request, unless it's a typo or a really obvious error.** Pull requests are the best way to propose changes to the specification. Get familiar with our document that explains [Git workflow](https://github.com/asyncapi/community/blob/master/docs/010-contribution-guidelines/git-workflow.md) used in our repositories. +## AI-Assisted Contributions + +You may use generative AI and AI-assisted tooling to help you contribute, but you remain the author of and are fully accountable for everything you submit. Before submitting AI-assisted work, review it thoroughly, verify it meets our standards, remove unrelated changes, and confirm it does not violate any licenses. + +If a contribution was materially AI-assisted, you **must** disclose it: add a `Generated-by: ` line to your pull request description (the PR template includes a dedicated section), or check the "No AI assistance" box. A CI check verifies that one of the two is present. + +Read the full [AI Usage Policy](AI-POLICY.md) for details, including the functions that are off-limits for automation. + ## Conventional Commits Our repositories follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) specification. Releasing to GitHub and NPM is done with the support of [semantic-release](https://semantic-release.gitbook.io/semantic-release/). diff --git a/README.md b/README.md index bedadfb694..66ef468fb0 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,8 @@ For the development setup, you can follow the detailed guide in [Development gui Read [CONTRIBUTING](CONTRIBUTING.md) guide. +If you use generative AI or AI-assisted tooling when contributing, read our [AI Usage Policy](AI-POLICY.md) first. + ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): From 674ff019a01eaa93caed1f339f8d515e65149885 Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Mon, 1 Jun 2026 23:36:14 +0200 Subject: [PATCH 2/5] Update AI-POLICY.md --- AI-POLICY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AI-POLICY.md b/AI-POLICY.md index c7d19acecc..7738b939d2 100644 --- a/AI-POLICY.md +++ b/AI-POLICY.md @@ -38,7 +38,7 @@ If a contribution was materially AI-assisted, you **must** disclose it: - **Pull requests:** include a `Generated-by:` line in the PR description naming the tool and its version, for example: - ``` + ```text Generated-by: Claude Code 1.x Generated-by: GitHub Copilot ``` From 83c83214f990ff885fa9ae1374c0e8809e90d7aa Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Sat, 6 Jun 2026 12:46:08 +0200 Subject: [PATCH 3/5] Update pull-request-template.md --- .github/pull-request-template.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/pull-request-template.md b/.github/pull-request-template.md index 766c709660..74970b19db 100644 --- a/.github/pull-request-template.md +++ b/.github/pull-request-template.md @@ -16,7 +16,7 @@ For example, `Resolves #123`, `Fixes #43`, or `See also #33`. The 3rd option wil **AI assistance** +Check exactly one box. If this PR was materially AI-assisted, keep the Generated-by line and fill in the tool + model version. --> - [ ] This PR was created with AI assistance — `Generated-by:` -- [ ] No AI assistance was used \ No newline at end of file +- [ ] No AI assistance was used From b5f3e6609cb907721a92769f5a35adf5c84c5d6b Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Sat, 6 Jun 2026 12:46:25 +0200 Subject: [PATCH 4/5] Update AI-assisted contribution disclosure requirements --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 96657f53a6..63fefbdf74 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -110,7 +110,7 @@ Please use our issues templates that provide you with hints on what information You may use generative AI and AI-assisted tooling to help you contribute, but you remain the author of and are fully accountable for everything you submit. Before submitting AI-assisted work, review it thoroughly, verify it meets our standards, remove unrelated changes, and confirm it does not violate any licenses. -If a contribution was materially AI-assisted, you **must** disclose it: add a `Generated-by: ` line to your pull request description (the PR template includes a dedicated section), or check the "No AI assistance" box. A CI check verifies that one of the two is present. +If a contribution was materially AI-assisted, you **must** disclose it: add a `Generated-by: ` line to your pull request description (the PR template includes a dedicated section), or check the "No AI assistance" box. A CI check verifies that one of the two is present. Read the full [AI Usage Policy](AI-POLICY.md) for details, including the functions that are off-limits for automation. From ec773eae983aa011de2c123408c2abffe6abcf32 Mon Sep 17 00:00:00 2001 From: derberg Date: Tue, 16 Jun 2026 09:07:56 +0200 Subject: [PATCH 5/5] Update CODEOWNERS --- CODEOWNERS | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CODEOWNERS b/CODEOWNERS index 2f2246b9c5..83efca9a0a 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -19,3 +19,7 @@ packages/ @Adi-204 @derberg @magicmatatjahu @asyncapi-bot-eve # Changeset markdown files — override so Docs Champions aren't requested .changeset/**/*.md @derberg @magicmatatjahu @asyncapi-bot-eve + +# AI agent instruction files — override so Docs Champions aren't requested +AGENTS.md @Adi-204 @derberg @magicmatatjahu @asyncapi-bot-eve +CLAUDE.md @Adi-204 @derberg @magicmatatjahu @asyncapi-bot-eve