From b4317a2f84bd8db202f07552d3f757c8e0fcee93 Mon Sep 17 00:00:00 2001 From: Andy Scherzinger Date: Mon, 16 Nov 2026 15:13:19 +0100 Subject: [PATCH] docs(ai-policy): allow AI-drafted text written for human readers The policy required issues, PR descriptions and review comments to be in the contributor's own words, so agent-drafted text had to be retyped by hand. Allow AI-drafted text written for humans and judge the result: maintainers ask for a rewrite before closing, and PRs opened before a policy change are asked to adapt rather than closed. Ask for PR descriptions that answer the reviewer's first questions, reproducible bug reports, commit messages that explain why, and live testing for every runtime change. Rewrite the snippet's "never do" list as "don't X, instead Y" so smaller models can follow it, and replace example models that are retired or never existed. Co-authored-by: MiMoHo <37556964+MiMoHo@users.noreply.github.com> Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Andy Scherzinger --- .github/workflows/ai-policy.yml | 2 +- AGENT_MD_SNIPPETS.md | 24 +++++++++++++--------- AI_POLICY.md | 34 +++++++++++++++++++++----------- CONTRIBUTING.md | 6 +++--- workflow-templates/ai-policy.yml | 2 +- 5 files changed, 43 insertions(+), 25 deletions(-) diff --git a/.github/workflows/ai-policy.yml b/.github/workflows/ai-policy.yml index 9b6d4943..5e7e42cc 100644 --- a/.github/workflows/ai-policy.yml +++ b/.github/workflows/ai-policy.yml @@ -169,7 +169,7 @@ jobs: echo "Please amend the affected commit(s) to remove the coding-agent sign-off" echo "and replace it with an 'Assisted-by' trailer, for example:" echo "" - echo " Assisted-by: Claude Code:claude-sonnet-4-6" + echo " Assisted-by: ClaudeCode:claude-sonnet-5-5" echo "" echo "References:" echo " • AGENTS.md (this repository)" diff --git a/AGENT_MD_SNIPPETS.md b/AGENT_MD_SNIPPETS.md index 4387edac..b7a8a0b9 100644 --- a/AGENT_MD_SNIPPETS.md +++ b/AGENT_MD_SNIPPETS.md @@ -8,12 +8,17 @@ All contributions generated or assisted by this agent must fully comply with: - **[AI Contribution Policy](https://github.com/nextcloud/.github/blob/master/AI_POLICY.md)** - the primary reference for AI-specific rules, covering disclosure, author accountability, communication, security, licensing, code quality, and autonomous agent behavior. -- **[Contribution Guidelines](https://github.com/nextcloud/.github/blob/master/CONTRIBUTING.md)** - covering testing requirements, the Developer Certificate of Origin (DCO), license headers, conventional commits, and translations. These apply in full to all contributions regardless of how they were produced. +- **[Contribution Guidelines](https://github.com/nextcloud/.github/blob/master/CONTRIBUTING.md)** - covering testing requirements, the Developer Certificate of Origin (DCO), license headers, and translations. These apply in full to all contributions regardless of how they were produced. ### What this agent must always do - Add an `Assisted-by: AGENT_NAME:MODEL_VERSION` git trailer to every commit containing AI-assisted content. -- Ensure every pull request includes a disclosure of AI tool use in the PR description. +- Ensure every pull request includes a disclosure of AI tool use in the PR description, and end every AI-drafted issue or comment with a footer such as `Assisted by AGENT_NAME:MODEL_VERSION`. +- Write issues, PR descriptions, and comments for human readers: + - Lead with what changed and why it matters, in plain and concise sentences. + - Keep the repository's PR or issue template intact and fill in every section. For a bug report, also state whether the bug was validated and reproduced on a live Nextcloud instance. + - Put information meant only for agents (plans, prompts, tool logs) into a collapsed `
` block. +- Write commit message bodies that explain why the change was made, not how; the diff already shows what changed. Keep the repository's commit conventions and the required trailers. - Produce focused, scoped pull requests that address exactly one concern. Do not touch unrelated files or introduce incidental refactors. - Verify all dependencies against actual package registries before suggesting them. Do not use hallucinated or unverified package names. - Write code comments that document the code, never the process that produced it: @@ -24,15 +29,16 @@ All contributions generated or assisted by this agent must fully comply with: - Reuse existing helper functions and utilities instead of re-implementing their logic inline. When fixing a flawed pattern, fix every occurrence of it across the changed code, not only the instance that was pointed out. - Run permission and access-control checks before the operation they guard, never after it and never only in the UI layer. - When adding or changing user-facing functionality, wire it up in every context where the affected component is used - the default authenticated view, public share pages, and embedded contexts such as the Smart Picker and reference widgets. When emitting new events, verify that every consumer of the component subscribes to and handles them. +- Validate every change to runtime behavior on a live Nextcloud instance where you can, and give the contributor concrete steps to test it there themselves. Your testing supports theirs; it does not replace it. - Explicitly inform the contributor when any action they are about to take, or have taken, would violate the AI Contribution Policy or the Contribution Guidelines. Do not silently proceed. State which rule is at risk and what the contributor should do instead. - Warn the contributor if a pull request is growing too large. A PR approaching several thousand lines of changed code is a signal that it should be split into smaller, focused PRs. Suggest a logical split before the PR is opened, not after. - Recommend opening a ticket for discussion before starting implementation whenever a feature or change is sufficiently complex - for example when it touches multiple subsystems, requires architectural decisions, or the right approach is not yet clear. A ticket allows maintainers and the contributor to align on direction before code is written, avoiding wasted effort on a PR that may be rejected or require fundamental rework. -### What this agent must never do +### What this agent must never do, and what to do instead -- Open issues, submit pull requests, post review comments, or send security reports autonomously. Every contribution must be reviewed and submitted by a human. -- Add `Signed-off-by` tags to commits. Only the human contributor can certify the Developer Certificate of Origin. -- Generate or submit security reports without independent human verification. Report verified vulnerabilities via [HackerOne](https://hackerone.com/nextcloud), not as GitHub issues. -- Write PR descriptions, review comments, or issue reports on behalf of the contributor. These must be in the contributor's own words. -- Fully automate the resolution of issues labeled [`good first issue`](https://github.com/issues?q=org%3Anextcloud+label%3A%22good+first+issue%22) or similar beginner-friendly labels. -- Submit code that has not been reviewed and cleaned up by the contributor. Dead code, redundant logic, excessive comments, malformed or garbled characters (e.g. `�` replacement characters), and unrelated changes must be removed before submission. +- Don't open issues, submit pull requests, or post comments on your own initiative. Instead, post only what the contributor asked for, on their behalf, and tell them what you posted. +- Don't write texts for machines: no file-by-file restatement of the diff, no filler, no raw tool output. Instead, write short, skimmable text for a human reviewer that explains what changed and why. +- Don't add `Signed-off-by` tags to commits. Instead, leave the sign-off to the contributor, who certifies the Developer Certificate of Origin with `git commit -s`. +- Don't submit security reports or open GitHub issues for vulnerabilities. Instead, hand your findings to the contributor to verify independently and report via [HackerOne](https://hackerone.com/nextcloud). +- Don't fully automate the resolution of issues labeled [`good first issue`](https://github.com/issues?q=org%3Anextcloud+label%3A%22good+first+issue%22) or similar beginner-friendly labels. Instead, explain the code and guide the contributor so they can solve the issue themselves. +- Don't hand over code with dead code, redundant logic, excessive comments, malformed or garbled characters (e.g. `�` replacement characters), or unrelated changes. Instead, remove them, and ask the contributor to review and clean up the result before submitting. diff --git a/AI_POLICY.md b/AI_POLICY.md index 79350579..c4a1466b 100644 --- a/AI_POLICY.md +++ b/AI_POLICY.md @@ -30,21 +30,31 @@ The PR description disclosure explains how AI was used; the commit trailer ensur Examples: ``` -Assisted-by: Devstral:devstral-small-2507 -Assisted-by: ClaudeCode:claude-sonnet-4-6 -Assisted-by: Qwen:qwen3-coder-32b -Assisted-by: Copilot:gpt-4o +Assisted-by: Devstral:devstral-small-2-24b-instruct-2512 +Assisted-by: ClaudeCode:claude-sonnet-5-5 +Assisted-by: Qwen:qwen3-coder-next +Assisted-by: Codex:gpt-6.1-sol ``` ### Author Accountability -The contributor is the legal and moral author of every line they submit. If a reviewer asks "why does this work this way?" and the answer is "the AI wrote it," the PR will be closed. This applies to code, comments, documentation, and tests alike. You must be able to explain, defend, and modify any content you submit. +The contributor is the legal and moral author of every line they submit, and is responsible for it however it was produced. This applies to code, comments, documentation, and tests alike. "The AI wrote it" is not an answer to a reviewer's question: answers may be drafted with AI, but they must actually address the question. -### Human-Written Communication +### Communication Written for Humans -Issues, PR descriptions, and review comments must be in the contributor's own words. Translation assistance and grammar/spelling help are acceptable exceptions and do not need to be disclosed - the intent of this rule is to ensure that the ideas, reasoning, and decisions in community communication come from the contributor. +Issues, PR descriptions, review comments, and replies may be drafted with AI assistance. Every such text is read by people - maintainers, reviewers, and future contributors - so it must be written for them: -This requirement extends through the entire review process. Contributors must respond to reviewer questions and implement requested changes themselves. Passing maintainer feedback into an AI and posting whatever comes out is not an acceptable substitute for genuine engagement. If a contributor cannot explain or implement a requested change because they do not understand their own submission, the PR will be closed. +- **Owned by the contributor.** Text posted on the contributor's behalf is theirs, no matter who drafted it. +- **Answers the reviewer's first questions.** A PR description states which problem it solves, what changed at a high level, and how to verify the change. A reviewer who has not read the code yet can tell all three from the description alone. +- **Plain, concise, and skimmable.** Do not restate the diff file by file, pad the text with filler or summaries of summaries, or paste raw tool output. +- **Disclosed.** Tick the AI checkbox of the repository's PR template, and end AI-drafted comments and issues with a footer such as `Assisted by AGENT_NAME:MODEL_VERSION`. +- **Template filled in.** When opening a PR or issue, keep the repository's template intact and complete every section. +- **Bug reports reproducible.** An AI-drafted bug report follows the repository's issue template and states whether the bug was validated and reproduced on a live Nextcloud instance. +- **Agent-only details collapsed.** Information meant only for other agents (prompts, plans, tool logs) goes into a collapsed `
` block, so human readers can skip it. + +Translation assistance and grammar/spelling help do not need to be disclosed. + +This applies throughout the review process: answers to reviewer questions and implementations of requested changes may be drafted with AI as well. What counts is the result. A pull request that is correct and well made is welcome, regardless of how much of it was produced with AI, as long as it meets the requirements of this policy. If a maintainer gets the impression that the contributor does not understand their own submission and is only relaying an AI whose output is of poor quality, they may first ask for a rewrite - by requesting changes or converting the pull request to a draft - and name what is missing, or close the pull request right away: such a contribution has no value to the project. If a rewrite was requested, the pull request may be closed when the contributor does not respond within a month, or when the rewrite still shows neither understanding nor quality. Extractive contributions can still be closed right away, see Maintainer Discretion. ### Security and Dependency Scrutiny @@ -54,7 +64,7 @@ For general security requirements applicable to all contributions, see the [Cont ### No Autonomous Agent Submissions -AI agents must not open issues, submit pull requests, post review comments, or send security reports autonomously. Every contribution must be composed, reviewed, and submitted by a human. This includes agentic workflows where an AI browses the codebase, plans changes across multiple files, and generates commits - the human contributor remains responsible for reviewing all output before anything is submitted. +AI agents must not act on their own: every issue, pull request, and comment is posted on behalf of a contributor who directed the agent and is accountable for it, and security reports are always submitted by a human. This includes agentic workflows where an AI browses the codebase, plans changes across multiple files, and generates commits - the human contributor remains responsible for everything that is submitted. AI agents must not add `Signed-off-by` tags: only humans can legally certify the [Developer Certificate of Origin](https://github.com/nextcloud/server/blob/master/contribute/developer-certificate-of-origin). @@ -70,11 +80,13 @@ AI output must be cleaned before submission. Dead code, redundant logic, excessi Code comments must document the code itself - behavior, signatures, and constraints the code cannot express - never the process that produced it. Progress notes, decision records, and change descriptions ("changed X to Y", "as requested", "this fixes ...") belong in the commit message or PR discussion; in code they go stale and become misleading. Comments must stay brief and match the comment density of the surrounding code, and self-explanatory code needs no comment at all. +Commit messages follow the repository's conventions, such as conventional commits and the trailers this policy requires. Beyond that, the message body explains why the change was made - the problem it solves and the decisions the diff does not show - not how it was done; the diff already shows that. + Duplicated logic is a further common sign of unreviewed AI output: existing helpers and utilities must be reused instead of re-implemented, and when a flawed pattern is corrected, every occurrence of it must be fixed - not only the one a reviewer happened to point out. Signs of a disallowed submission include: large unreviewed AI blobs; obvious mechanical mistakes a human would fix in minutes; code that has clearly never been executed; and pull requests that shift debugging and cleanup work onto maintainers rather than the contributor. As required by the [Contribution Guidelines](CONTRIBUTING.md), all changed and added code must be unit tested - AI-generated code is not exempt from this requirement. -New features must be tested on a live Nextcloud instance by the contributor before submission, and in every context in which they are reachable - not only the default authenticated view, but also public share links, embedded contexts such as the Smart Picker and reference widgets, and other entry points the app supports. AI-generated changes frequently work in the primary view while silently failing in secondary ones. Providing test instructions for an AI agent to execute is not a substitute for human testing. +Every pull request that changes runtime behavior must be validated by testing it on a live Nextcloud instance before submission, in every context in which the change is reachable - not only the default authenticated view, but also public share links, embedded contexts such as the Smart Picker and reference widgets, and other entry points the app supports. AI-generated changes frequently work in the primary view while silently failing in secondary ones. This testing may be AI-assisted, but must not be limited to it: the contributor tests the change on the live instance themselves as well. --- @@ -96,4 +108,4 @@ AI tools must not be used to fully automate the resolution of issues labeled [`g ## Scope and Updates -This policy applies to all contributions to repositories and apps under the Nextcloud GitHub organization, by all contributors. It will be reviewed and updated as AI tooling, open-source best practices, and applicable law evolve. Suggested changes are welcome via pull requests. \ No newline at end of file +This policy applies to all contributions to repositories and apps under the Nextcloud GitHub organization, by all contributors. It will be reviewed and updated as AI tooling, open-source best practices, and applicable law evolve. Pull requests opened before a change to this policy are asked to adapt to it rather than closed. Suggested changes are welcome via pull requests. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2f6d46f4..463d44ae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,11 +31,11 @@ Nextcloud allows contributions made with the help of AI tools. You are the autho * **Disclosure:** Declare AI tool use in the PR description and add an `Assisted-by: AGENT_NAME:MODEL_VERSION` git trailer to each affected commit. -* **Accountability:** You must be able to explain, defend, and modify every line you submit. If a reviewer asks why something works a certain way, "the AI wrote it" is not an answer. +* **Accountability:** You are responsible for every line you submit, however it was produced. If a reviewer asks why something works a certain way, "the AI wrote it" is not an answer. -* **Communication:** PR descriptions, review comments, and issue reports must be written in your own words. This applies throughout the review process - passing reviewer feedback to an AI and posting whatever comes out is not acceptable. +* **Communication:** PR descriptions, review comments, issue reports, and answers to reviewers may be drafted with AI, but they must be written for human readers: plain, concise, and disclosed. If a pull request shows neither understanding nor quality, maintainers may ask for a rewrite first and close it if nothing improves. -* **Quality:** AI output must be quality assured by the human, i.e. reviewed, cleaned up, and tested before submission. New features must be tested on a live instance by you, not by an agent. Code that has never been executed, or that shifts debugging work onto maintainers, will not be accepted. +* **Quality:** AI output must be quality assured by the human, i.e. reviewed, cleaned up, and tested before submission. Every pull request that changes runtime behavior must be validated on a live instance; an agent may help with that testing, but you test the change yourself as well. Code that has never been executed, or that shifts debugging work onto maintainers, will not be accepted. * **Licensing:** Ensure AI-generated code contains no material incompatible with the license of the repository you are contributing to. diff --git a/workflow-templates/ai-policy.yml b/workflow-templates/ai-policy.yml index 9b6d4943..5e7e42cc 100644 --- a/workflow-templates/ai-policy.yml +++ b/workflow-templates/ai-policy.yml @@ -169,7 +169,7 @@ jobs: echo "Please amend the affected commit(s) to remove the coding-agent sign-off" echo "and replace it with an 'Assisted-by' trailer, for example:" echo "" - echo " Assisted-by: Claude Code:claude-sonnet-4-6" + echo " Assisted-by: ClaudeCode:claude-sonnet-5-5" echo "" echo "References:" echo " • AGENTS.md (this repository)"