From c7a044b8355ed762bbc0bc634a903b8bc97668a6 Mon Sep 17 00:00:00 2001 From: Andy Scherzinger Date: Fri, 20 Nov 2026 13:02:50 +0100 Subject: [PATCH 1/2] docs: sync AGENTS.md with AI policy update from nextcloud/.github#839 The org-wide AI policy now allows AI-drafted issues, PR descriptions and comments as long as they are written for human readers, disclosed and posted on the contributor's behalf. The agent instructions still told agents never to write such text, which contradicts the policy they point to. The repository-specific test rule is aligned as well: runtime changes must be validated on a live instance, and agent testing may support but not replace the contributor's own testing. Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Andy Scherzinger --- AGENTS.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 80213506bd332..e5801ef670eb2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,12 +14,17 @@ This file provides instructions for AI coding agents (Claude Code, GitHub Copilo 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: @@ -30,19 +35,20 @@ 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. - When adding a new PHP file, run build/autoloaderchecker.sh -### 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. --- @@ -69,14 +75,14 @@ Example: ``` feat(files_sharing): allow sharing with contacts -Assisted-by: ClaudeCode:claude-sonnet-4-6 +Assisted-by: ClaudeCode:claude-sonnet-5-5 ``` ### Tests - Every changed or added code segment must be covered by unit tests. Pull requests without tests for new or modified logic will not be accepted. - In areas where unit testing is currently difficult, refactoring to enable testability is encouraged alongside the bug fix. -- New features must be manually tested on a live Nextcloud instance by the human contributor before submission. Providing test steps for an agent to execute is not a substitute. +- Every change to runtime behavior must be validated on a live Nextcloud instance before submission. An agent may help with that testing, but the human contributor tests the change themselves as well. - You can run tests with `NOCOVERAGE=0 ./autotest.sh ` with db being either sqlite or pgsql ### Developer Certificate of Origin (DCO) From be691e8bc29835d8884a2a30b89840d9058d74db Mon Sep 17 00:00:00 2001 From: Andy Scherzinger Date: Sat, 21 Nov 2026 13:33:50 +0100 Subject: [PATCH 2/2] docs: sync AI section of the contributing guide with nextcloud/.github#839 The contributing guide still required PR descriptions and comments in the contributor's own words and live testing only for new features. Bring its AI section in line with the org-wide contributing guide. Assisted-by: ClaudeCode:claude-opus-5-5 Signed-off-by: Andy Scherzinger --- .github/CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 2d168e1c47508..b6f0a7ff5bbf0 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -41,11 +41,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.