diff --git a/AGENT_MD_SNIPPETS.md b/AGENT_MD_SNIPPETS.md new file mode 100644 index 0000000..73de185 --- /dev/null +++ b/AGENT_MD_SNIPPETS.md @@ -0,0 +1,30 @@ + + +## Nextcloud Contribution Policy + +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. + +### 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. +- 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. +- 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 + +- 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, and unrelated changes must be removed before submission. diff --git a/AI_POLICY.md b/AI_POLICY.md new file mode 100644 index 0000000..53b4547 --- /dev/null +++ b/AI_POLICY.md @@ -0,0 +1,95 @@ + + +# AI Contribution Policy + +This document provides guidance for AI tools and developers using AI assistance when contributing to Nextcloud. It applies to all repositories under the [Nextcloud GitHub organization](https://github.com/nextcloud/), including the server, clients, apps, and the community app ecosystem. + +This policy complements the existing [Contribution Guidelines](CONTRIBUTING.md). The requirements around testing, the Developer Certificate of Origin, license headers, and security reporting described there continue to apply in full - this document addresses how they extend to AI-assisted contributions. + +--- + +## Requirements + +### Disclosure + +Every pull request containing AI-assisted code, documentation, or tests must declare this in the PR description. PRs found to have undisclosed AI use might be closed. + +For full traceability at the commit level, each commit containing AI-assisted content must include an `Assisted-by:` git trailer: + +``` +Assisted-by: AGENT_NAME:MODEL_VERSION +``` + +The agent name and model version identify the AI tool. Basic development tools such as git, compilers, editors, and static analyzers are not listed - these are standard parts of any development workflow regardless of AI involvement. + +The PR description disclosure explains how AI was used; the commit trailer ensures that provenance is permanently recorded in version history and available to future contributors, auditors, and tooling. + +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 +``` + +### 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. + +### Human-Written Communication + +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. + +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. + +### Security and Dependency Scrutiny + +AI tools hallucinate package names, produce subtly broken access controls, and may reproduce vulnerable patterns from their training data. Contributors must manually verify all dependencies, access control logic, authentication patterns, and security implications in AI-generated code before submitting - the risk of undetected errors is higher than with hand-written code and warrants extra care. + +For general security requirements applicable to all contributions, see the [Contribution Guidelines](CONTRIBUTING.md). Security vulnerabilities must be reported via [HackerOne](https://hackerone.com/nextcloud) following Nextcloud's [security policy](https://nextcloud.com/security/), not via public issues. AI-generated security reports must be independently verified before submission; unverified reports might be closed without response. + +### 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 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). + +### Licensing and Copyright Compliance + +Contributors must ensure AI-generated code contains no material from sources incompatible with the license of the repository or app they are contributing to. Each Nextcloud repository and app carries its own license - contributors are responsible for knowing which applies. For guidance on license headers, see [HowToApplyALicense.md](https://github.com/nextcloud/server/blob/master/contribute/HowToApplyALicense.md). + +The applicable test has three parts: the AI tool's terms must permit open-source use of its output; no third-party copyrighted material may be reproduced; and any included material must use a compatible open-source license. If generated code appears identical or suspiciously similar to code from an incompatible source, it must be removed or replaced with an original implementation. Ignorance of AI-generated provenance is not a defense. + +### Code Quality and Cleanup + +AI output must be cleaned before submission. Dead code, redundant logic, excessive comments, inconsistent style, unused variables, structural drift, and unrelated file changes must all be removed. Submitting large AI code blobs without meaningful oversight - sometimes called "vibe coding" or "prompt dumping" - is prohibited. + +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. Providing test instructions for an AI agent to execute is not a substitute for human testing. + +--- + +## Guidelines + +### Focused and Scoped Pull Requests + +A pull request should address exactly one thing. AI-generated code frequently drifts in scope due to imprecise prompting, touching unrelated files or introducing incidental refactors. If a PR description does not match its diff, that is a signal the contributor did not review their own changes. Large changes must be broken into multiple focused commits or separate PRs. + +### Maintainer Discretion + +Maintainers have unreviewable authority to close AI-assisted contributions for quality, complexity, scope, or community-fit reasons. A contribution that costs reviewers more time than it returns value to the project is extractive and will be closed, regardless of how many rounds of review it has already received. The golden rule applies: a contribution should be worth more to the project than the time it takes to review. + +### Beginner Issues + +AI tools must not be used to 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. These issues exist to create a learning path for new contributors who will become future maintainers. Take a beginner issue only if you genuinely intend to learn and continue contributing to Nextcloud. + +--- + +## 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 200fae9..2f6d46f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,6 +25,22 @@ Thanks for wanting to contribute source code to Nextcloud. That's great! Please read the [Developer Manuals][devmanual] to learn how to create your first application or how to test the Nextcloud code. +### AI-assisted contributions + +Nextcloud allows contributions made with the help of AI tools. You are the author of everything you submit - AI assistance does not change that responsibility. + +* **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. + +* **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. + +* **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. + +* **Licensing:** Ensure AI-generated code contains no material incompatible with the license of the repository you are contributing to. + +For the full policy including autonomous agent rules, security reports, and beginner issues, read the [AI Contribution Policy][aipolicy]. + ### Tests In order to constantly increase the quality of our software we can no longer accept pull request which submit un-tested code. @@ -57,6 +73,7 @@ In case you are not sure how to add or update the license header correctly pleas [devmanual]: https://docs.nextcloud.com/server/latest/developer_manual/ [dcofile]: https://github.com/nextcloud/server/blob/master/contribute/developer-certificate-of-origin [applyalicense]: https://github.com/nextcloud/server/blob/master/contribute/HowToApplyALicense.md +[aipolicy]: https://github.com/nextcloud/.github/blob/master/AI_POLICY.md ## Translations Please submit translations via [Transifex][transifex].