diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 549e85a263fa4..ecd8f9fb27fdb 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -29,3 +29,5 @@ https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin ## AI (if applicable) - [ ] The content of this PR was partly or fully generated using AI + - [ ] I have read the [guidelines for AI-assisted contributions](https://github.com/nextcloud/desktop/blob/master/CONTRIBUTING.md#ai-assisted-contributions). + - [ ] I have read Nextcloud's [AI Contribution Policy](https://github.com/nextcloud/.github/blob/master/AI_POLICY.md). diff --git a/AGENTS.md b/AGENTS.md index a326bd0787b17..4d0cc1f8f1e8f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,12 +6,6 @@ You are an experienced engineer specialized on C++ and Qt and familiar with the platform-specific details of Windows, macOS and Linux. -## Your Role - -- You implement features and fix bugs. -- Your documentation and explanations are written for less experienced contributors to ease understanding and learning. -- You work on an open source project and lowering the barrier for contributors is part of your work. - ## Project Overview The Nextcloud Desktop Client is a tool to synchronize files from Nextcloud Server with your computer. @@ -19,6 +13,38 @@ Qt, C++, CMake and KDE Craft are the key technologies used for building the app Beyond that, there are platform-specific extensions of the multi-platform app in the `./shell_integration` directory. Other platforms like iOS and Android are irrelevant for this project. +## 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/desktop/blob/master/.github/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. + +## Your Role + +- You implement features and fix bugs. +- Your documentation and explanations are written for less experienced contributors to ease understanding and learning. +- You work on an open source project and lowering the barrier for contributors is part of your work. + ## Project Structure: AI Agent Handling Guidelines | Directory | Description | Agent Action | @@ -30,24 +56,58 @@ Other platforms like iOS and Android are irrelevant for this project. | `./translations` | Translation files from Transifex. | Do not modify | | `.mac-crafter` | Build artifacts and derived data. | Ignore | + ## General Guidance -Every new file needs to get a SPDX header in the first rows according to this template. -The year in the first line must be replaced with the year when the file is created (for example, 2026 for files first added in 2026). -The commenting signs need to be used depending on the file type. +### License headers + +Every new file must include the correct SPDX license header. For AGPL-2.0-or-later (the default for this repository): ```plaintext SPDX-FileCopyrightText: Nextcloud GmbH and Nextcloud contributors SPDX-License-Identifier: GPL-2.0-or-later ``` +The commenting signs need to be used depending on the file type. + +See [HowToApplyALicense.md](https://github.com/nextcloud/server/blob/master/contribute/HowToApplyALicense.md) for details on per-language formats. AI-generated code must not include material from sources incompatible with AGPL-2.0-or-later. Avoid creating source files that implement multiple types; instead, place each type in its own dedicated source file. ## Commit and Pull Request Guidelines -- **Commits**: Follow Conventional Commits format. Use `feat: ...`, `fix: ...`, or `refactor: ...` as appropriate in the commit message prefix. -- Include a short summary of what changed. *Example:* `fix: prevent crash on empty todo title`. -- **Pull Request**: When the agent creates a PR, it should include a description summarizing the changes and why they were made. If a GitHub issue exists, reference it (e.g., “Closes #123”). +### Commit format + +Use [Conventional Commits](https://www.conventionalcommits.org) for all commit messages: + +``` +(): + +[optional body] + +Assisted-by: AGENT_NAME:MODEL_VERSION +``` + +- Use `feat: ...`, `fix: ...`, or `refactor: ...` as appropriate in the commit message prefix. +- Include a short summary of what changed. *Example:* `fix: prevent crash on empty todo title`. If a GitHub issue exists, reference it (e.g., “Closes #123”). + +Example: +``` +feat(files_sharing): allow sharing with contacts + +Closes #123. + +Assisted-by: ClaudeCode:claude-sonnet-4-6 +``` + +### Developer Certificate of Origin (DCO) + +The project uses the DCO as an additional safeguard. Only the human contributor may add the `Signed-off-by` trailer - agents must not add it: + +``` +Signed-off-by: Random J Developer +``` + +Contributors can sign automatically with `git commit -s` after configuring `user.name` and `user.email`. ## macOS Specifics diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92753f1b00062..d1eaa654f7199 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,7 +34,23 @@ Please read the [Contribution Guide](https://nextcloud.com/contribute/) to get started and follow the [Coding Style](https://github.com/nextcloud/desktop/wiki/Coding-Style) when writing new code. -### Sign your work +## 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. +s +* **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](https://github.com/nextcloud/.github/blob/master/AI_POLICY.md). + +## Sign your work We use the Developer Certificate of Origin (DCO) as an additional safeguard for the Nextcloud project. This is a well established and widely used @@ -52,7 +68,10 @@ commit automatically with `git commit -s`. You can also use git [aliases](https: like `git config --global alias.ci 'commit -s'`. Now you can commit with `git ci` and the commit will be signed. +## Apply a license + +In case you are not sure how to add or update the license header correctly please have a look at [contribute/HowToApplyALicense.md](https://github.com/nextcloud/server/blob/master/contribute/HowToApplyALicense.md). ## Translations -Please submit translations via [Transifex](https://explore.transifex.com/nextcloud/). +Please submit translations via [Transifex](https://explore.transifex.com/nextcloud/). \ No newline at end of file