From a04b7323db002f543d443d66a4c023b7e36e1de7 Mon Sep 17 00:00:00 2001 From: Milen Pivchev Date: Thu, 12 Mar 2026 15:57:08 +0100 Subject: [PATCH 1/9] Add an AGENTS.md Signed-off-by: Milen Pivchev --- AGENTS.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..0ed573fa95 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,74 @@ + + +# Agents.md + +You are an experienced engineer specialized in Swift and familiar with the platform-specific details of iOS. + +## 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 iOS Client is a tool to synchronize files from Nextcloud Server with your computer. +Swift, UIKit and SwiftUI are the key technologies used for building the app on iOS. +Beyond that, there is shared code in the form of the NextcloudKit library for use in Mac and iOS. +Other platforms like Android are irrelevant for this project. + +## Project Structure: AI Agent Handling Guidelines + +| Directory | Description | Agent Action | +|-----------------|-----------------------------------------------------|----------------------| +| `./github` | Github CI workflows. | Try to add a unit tests for new features, where applicable and makes sense. Do not overcomplicate unit tests. +| `./shell_integration/MacOSX/NextcloudIntegration` | Xcode project for macOS app extensions | Look here first for changes in context of the file provider extension | +| `/iOSClient/SupportingFiles` | Translation files from Transifex. | Only add new strings in `en.lproj`. The rest you should ignore. | +| `/DerivedData` | Build artifacts and derived data. | Ignore | +| `.xcode` | Build artifacts and derived data. | Ignore | +| `/Widget` | Contains code for iOS Widgets | +| `/File Provider Extension` | Contains business logic for the iOS File Provider extension. | +| `/File Provider Extension UI` | Contains UI logic for the iOS File Provider extension. | +| `/Share` | Contains code for the iOS Share extension. | + +## 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. + +```plaintext +SPDX-FileCopyrightText: Nextcloud GmbH and Nextcloud contributors +SPDX-License-Identifier: GPL-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”). + +## iOS Specifics + +The following details are important when working on the iOS client. + +### Requirements + +- Latest stable Xcode available is required to be installed in the development environment. + +### Code Style + +- When writing code in Swift, respect strict concurrency rules and Swift 6 compatibility. + +### Tests + +- When implementing new test suites, prefer Swift Testing over XCTest for implementation. +- When implementing test cases using Swift Testing, do not prefix test method names with "test". +- If the implementation of mock types is inevitable, implement them in dedicated source code files and in a generic way, so they can be reused across all tests in a test target. +- If the implementation of an existing mock type does not fulfill the requirements introduced by new tests, prefer updating the existing type before implementing a mostly redundant alternative type. +- Verify that all tests are passing and correct them if necessary. From bcf8b24f9bd21f43c7fb6639b5d1180d53a305f8 Mon Sep 17 00:00:00 2001 From: Milen Pivchev Date: Mon, 16 Mar 2026 13:01:26 +0100 Subject: [PATCH 2/9] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Milen Pivchev --- AGENTS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0ed573fa95..52a99e51f9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,10 +29,10 @@ Other platforms like Android are irrelevant for this project. | `/iOSClient/SupportingFiles` | Translation files from Transifex. | Only add new strings in `en.lproj`. The rest you should ignore. | | `/DerivedData` | Build artifacts and derived data. | Ignore | | `.xcode` | Build artifacts and derived data. | Ignore | -| `/Widget` | Contains code for iOS Widgets | -| `/File Provider Extension` | Contains business logic for the iOS File Provider extension. | -| `/File Provider Extension UI` | Contains UI logic for the iOS File Provider extension. | -| `/Share` | Contains code for the iOS Share extension. | +| `/Widget` | Contains code for iOS Widgets | — | +| `/File Provider Extension` | Contains business logic for the iOS File Provider extension. | — | +| `/File Provider Extension UI` | Contains UI logic for the iOS File Provider extension. | — | +| `/Share` | Contains code for the iOS Share extension. | — | ## General Guidance From 7bc20ad10e3505ea4b38a182484048443b060548 Mon Sep 17 00:00:00 2001 From: Milen Pivchev Date: Mon, 16 Mar 2026 13:01:41 +0100 Subject: [PATCH 3/9] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Milen Pivchev --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 52a99e51f9..35e45c7e36 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,7 +24,7 @@ Other platforms like Android are irrelevant for this project. | Directory | Description | Agent Action | |-----------------|-----------------------------------------------------|----------------------| -| `./github` | Github CI workflows. | Try to add a unit tests for new features, where applicable and makes sense. Do not overcomplicate unit tests. +| `./github` | GitHub CI workflows. | Try to add a unit tests for new features, where applicable and makes sense. Do not overcomplicate unit tests. | `./shell_integration/MacOSX/NextcloudIntegration` | Xcode project for macOS app extensions | Look here first for changes in context of the file provider extension | | `/iOSClient/SupportingFiles` | Translation files from Transifex. | Only add new strings in `en.lproj`. The rest you should ignore. | | `/DerivedData` | Build artifacts and derived data. | Ignore | From a4a4fb9459bddac54919941de1962eb7966fac5f Mon Sep 17 00:00:00 2001 From: Milen Pivchev Date: Mon, 16 Mar 2026 13:03:22 +0100 Subject: [PATCH 4/9] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Milen Pivchev --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 35e45c7e36..7554acd720 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,9 +15,9 @@ You are an experienced engineer specialized in Swift and familiar with the platf ## Project Overview -The Nextcloud iOS Client is a tool to synchronize files from Nextcloud Server with your computer. +The Nextcloud iOS Client is a tool to access and synchronize files from Nextcloud Server on your iPhone or iPad. Swift, UIKit and SwiftUI are the key technologies used for building the app on iOS. -Beyond that, there is shared code in the form of the NextcloudKit library for use in Mac and iOS. +Beyond that, there is shared code in the form of the NextcloudKit library for use in macOS and iOS. Other platforms like Android are irrelevant for this project. ## Project Structure: AI Agent Handling Guidelines From 2b98d2bd5f81f54a8a077a46423b533b1d3f9bbe Mon Sep 17 00:00:00 2001 From: Milen Pivchev Date: Mon, 16 Mar 2026 13:03:56 +0100 Subject: [PATCH 5/9] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Milen Pivchev --- AGENTS.md | 1 - 1 file changed, 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 7554acd720..09e0810249 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,7 +25,6 @@ Other platforms like Android are irrelevant for this project. | Directory | Description | Agent Action | |-----------------|-----------------------------------------------------|----------------------| | `./github` | GitHub CI workflows. | Try to add a unit tests for new features, where applicable and makes sense. Do not overcomplicate unit tests. -| `./shell_integration/MacOSX/NextcloudIntegration` | Xcode project for macOS app extensions | Look here first for changes in context of the file provider extension | | `/iOSClient/SupportingFiles` | Translation files from Transifex. | Only add new strings in `en.lproj`. The rest you should ignore. | | `/DerivedData` | Build artifacts and derived data. | Ignore | | `.xcode` | Build artifacts and derived data. | Ignore | From 7f24baf323294c263e471f9245eb6e8dd0e1014a Mon Sep 17 00:00:00 2001 From: Milen Pivchev Date: Mon, 16 Mar 2026 13:04:30 +0100 Subject: [PATCH 6/9] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Milen Pivchev --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 09e0810249..15077553e3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,9 +48,10 @@ Avoid creating source files that implement multiple types; instead, place each t ## Commit and Pull Request Guidelines -- **Commits**: Follow Conventional Commits format. Use `feat: ...`, `fix: ...`, or `refactor: ...` as appropriate in the commit message prefix. +- **DCO sign-off (required)**: All commits must comply with the Developer Certificate of Origin (DCO) as described in `README.md` and include a `Signed-off-by: …` line in the commit message. +- **Commits**: In addition to the DCO sign-off, follow the Conventional Commits format for the subject line where reasonable. 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”). +- **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”). If there is any discrepancy between this section and the contribution guidance in `README.md`, the rules in `README.md` take precedence. ## iOS Specifics From 59654d40c20505b0dbec2bf21adc1117e69a641e Mon Sep 17 00:00:00 2001 From: Milen Pivchev Date: Mon, 16 Mar 2026 13:04:45 +0100 Subject: [PATCH 7/9] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Milen Pivchev --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 15077553e3..b6f69c900a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,7 +3,7 @@ - SPDX-License-Identifier: GPL-2.0-or-later --> -# Agents.md +# AGENTS.md You are an experienced engineer specialized in Swift and familiar with the platform-specific details of iOS. From 04721cfd9d27cf3444586e118da0dd8a8ecd49c4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 12:05:09 +0000 Subject: [PATCH 8/9] Initial plan From 5e4912d62510d0dbf84e7f0eb898e8717660562a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 12:05:52 +0000 Subject: [PATCH 9/9] fix: correct .github directory name in AGENTS.md Signed-off-by: Copilot Co-authored-by: mpivchev <6960329+mpivchev@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index b6f69c900a..f3194a3122 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,7 +24,7 @@ Other platforms like Android are irrelevant for this project. | Directory | Description | Agent Action | |-----------------|-----------------------------------------------------|----------------------| -| `./github` | GitHub CI workflows. | Try to add a unit tests for new features, where applicable and makes sense. Do not overcomplicate unit tests. +| `.github` | GitHub CI workflows. | Try to add a unit tests for new features, where applicable and makes sense. Do not overcomplicate unit tests. | `/iOSClient/SupportingFiles` | Translation files from Transifex. | Only add new strings in `en.lproj`. The rest you should ignore. | | `/DerivedData` | Build artifacts and derived data. | Ignore | | `.xcode` | Build artifacts and derived data. | Ignore |