daenamnu/nextcloud
1
0
Fork 0
mirror of https://github.com/nextcloud/all-in-one.git synced 2026-09-19 17:50:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

add Contributing and agents.md files to the repo (#8295)

Browse Source 
* add AI-Policy and Contributing and agents.md files to the repo

Signed-off-by: Simon L. <szaimen@e.mail.de>

* Apply suggestions from code review

Co-authored-by: Pablo Zmdl <57864086+pabzm@users.noreply.github.com>
Signed-off-by: Simon L. <szaimen@e.mail.de>

* remove the ai-policy file

Signed-off-by: Simon L. <szaimen@e.mail.de>

* Apply suggestion from @szaimen

Signed-off-by: Simon L. <szaimen@e.mail.de>

* Apply suggestion from @szaimen

Signed-off-by: Simon L. <szaimen@e.mail.de>

---------

Signed-off-by: Simon L. <szaimen@e.mail.de>
Co-authored-by: Pablo Zmdl <57864086+pabzm@users.noreply.github.com>
This commit is contained in:
Simon L.
2026-06-17 13:42:23 +02:00
committed by GitHub
co-authored by Pablo Zmdl
parent 8584e1a5a4
commit 29d014489d
2 changed files with 188 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+112
View File
@@ -0,0 +1,112 @@
<!--
- SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
- SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Agent Guidelines for Nextcloud All-in-one
This file provides instructions for AI coding agents (Claude Code, GitHub Copilot, Cursor, Windsurf, and others) operating on this repository. Read it before generating any code, commits, or pull requests.
---
## 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/all-in-one/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.
- 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.
---
## Repository-Specific Requirements
### Commit format
Use [Conventional Commits](https://www.conventionalcommits.org) for all commit messages:
```
<type>(<scope>): <short description>
[optional body]
Assisted-by: AGENT_NAME:MODEL_VERSION
```
Common types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `build`, `ci`.
The scope should match the affected component or app (e.g. `files_sharing`, `core`, `encryption`).
Example:
```
feat(files_sharing): allow sharing with contacts
Assisted-by: ClaudeCode:claude-sonnet-4-6
```
### 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.
### 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 <random@developer.example.org>
```
Contributors can sign automatically with `git commit -s` after configuring `user.name` and `user.email`.
### License headers
Every new file must include the correct SPDX license header. For AGPL-3.0-or-later (the default for this repository):
```php
/**
* SPDX-FileCopyrightText: <year> <name>
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
```
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-3.0-or-later.
### Security
- Do not open GitHub issues for potential vulnerabilities. Report them via [HackerOne](https://hackerone.com/nextcloud) following the [security policy](https://nextcloud.com/security/).
- AI-generated security reports must be independently verified by the human contributor before submission.
- Manually verify all access control logic, authentication patterns, and dependency names - AI tools are known to hallucinate package names and reproduce vulnerable patterns.
### Scope of this repository
This repository covers the Nextcloud all-in-one and all its included containers and features. Issues and changes for other components belong in their respective repositories under the [Nextcloud GitHub organization](https://github.com/nextcloud/).
---
## Further Reading
- [Local CONTRIBUTING.md](CONTRIBUTING.md)
- [Nextcloud Contribution Guidelines](https://github.com/nextcloud/all-in-one/blob/main/CONTRIBUTING.md)
- [AI Contribution Policy](https://github.com/nextcloud/.github/blob/master/AI_POLICY.md)
- [Developer Certificate of Origin](https://github.com/nextcloud/server/blob/master/contribute/developer-certificate-of-origin)
- [How to Apply a License](https://github.com/nextcloud/server/blob/master/contribute/HowToApplyALicense.md)
- [Developer Manual](https://github.com/nextcloud/all-in-one/blob/main/develop.md)
- [Security Vulnerability Reporting (HackerOne)](https://hackerone.com/nextcloud)
CONTRIBUTING.md
+76
View File
@@ -0,0 +1,76 @@
<!--
SPDX-FileCopyrightText: 2021-2024 Nextcloud GmbH and Nextcloud contributors
SPDX-License-Identifier: MIT
-->
## Submitting issues
If you have questions about how to install or use Nextcloud, please direct these to our [forum][forum].
### Guidelines
* Please search the existing issues first, it's likely that your issue was already reported or even fixed.
- Go to one of the repositories, click "issues" and type any word in the top search/command bar.
- More info on [search syntax within github](https://help.github.com/articles/searching-issues)
* __SECURITY__: Report any potential security bug to us via [our HackerOne page](https://hackerone.com/nextcloud) following our [security policy](https://nextcloud.com/security/) instead of filing an issue in our bug tracker.
* The issues in other components should be reported in their respective repositories: You will find them in our [GitHub Organization](https://github.com/nextcloud/)
* Report the issue using one of our templates, they include all the information we need to track down the issue.
Help us to maximize the effort we can spend fixing issues and adding new features, by not reporting duplicate issues.
[forum]: https://help.nextcloud.com/
## Contributing to Source Code
Thanks for wanting to contribute source code to Nextcloud. That's great!
Please read the [general contribution guidelines][contributing] that apply to all Nextcloud repositories, and the [AI Contribution Policy][aipolicy] if you are using AI tools.
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
We are striving to increase the quality and reliability of our software by improving its test suite, and encourage to add or extend playwright test cases for every relevant code change.
### Sign your work
We use the Developer Certificate of Origin (DCO) as a additional safeguard
for the Nextcloud project. This is a well established and widely used
mechanism to assure contributors have confirmed their right to license
their contribution under the project's license.
Please read [contribute/developer-certificate-of-origin][dcofile].
If you can certify it, then just add a line to every git commit message:
````
Signed-off-by: Random J Developer <random@developer.example.org>
````
Use your real name (sorry, no pseudonyms or anonymous contributions).
If you set your `user.name` and `user.email` git configs, you can sign your
commit automatically with `git commit -s`. You can also use git [aliases](https://git-scm.com/book/tr/v2/Git-Basics-Git-Aliases)
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][applyalicense]
[devmanual]: https://github.com/nextcloud/all-in-one/blob/main/develop.md
[dcofile]: https://github.com/nextcloud/server/blob/master/contribute/developer-certificate-of-origin
[applyalicense]: https://github.com/nextcloud/server/blob/master/contribute/HowToApplyALicense.md
[contributing]: https://github.com/nextcloud/.github/blob/master/CONTRIBUTING.md
[aipolicy]: https://github.com/nextcloud/.github/blob/master/AI_POLICY.md