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 Forms is a Nextcloud app (PHP backend under OCA\Forms + Vue 3/TypeScript frontend) for creating surveys and questionnaires, sharing them with users, groups, teams or public links, collecting responses, and viewing or exporting results (CSV/XLSX, or synced to a linked spreadsheet file). It ships a versioned OCS REST API (v3) and integrates with Nextcloud activity, search, audit log, webhooks and the Analytics app. Supported server range is in appinfo/info.xml (<nextcloud min-version max-version>).
All contributions generated or assisted by this agent must fully comply with:
- AI Contribution Policy - the primary reference for AI-specific rules, covering disclosure, author accountability, communication, security, licensing, code quality, and autonomous agent behavior.
- Contribution Guidelines - 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.
- Add an
Assisted-by: AGENT_NAME:MODEL_VERSIONgit trailer to every commit containing AI-assisted content (see Commits). - Follow the repository's commit conventions, including Conventional Commits (see Commits).
- Declare AI use in every pull request description by ticking the AI checkbox of the pull request template, and end AI-drafted comments and issues with a footer such as
Assisted by AGENT_NAME:MODEL_VERSION. - Write issues, PR descriptions and replies for human readers: plain, concise and skimmable, without restating the diff file by file, filler or raw tool output. Keep the repository's template intact and complete every section. Put agent-only material (prompts, plans, tool logs) in a collapsed
<details>block. - State in a PR description which problem it solves, what changed at a high level, and how to verify the change.
- State in an AI-drafted bug report whether the bug was validated and reproduced on a live Nextcloud instance.
- Keep each pull request to exactly one concern, with a description that matches its diff; break large changes into focused commits or separate PRs.
- Clean the output before submission: remove dead code, redundant logic, excessive comments, inconsistent style, unused variables, garbled characters, structural drift and unrelated file changes.
- Write code comments that document the code itself (behaviour, signatures, constraints the code cannot express), never the process that produced it; keep them brief and matching the comment density of the surrounding code.
- Reuse existing helpers instead of re-implementing them, and when correcting a flawed pattern, fix every occurrence of it.
- Unit test all changed and added code.
- Validate every runtime change on a live Nextcloud instance in every context it is reachable from: the logged-in app, public share links and embedded forms. The contributor tests it on the live instance themselves as well, not only with AI.
- Manually verify all dependencies, access control logic, authentication patterns and other security implications of generated code.
- Keep generated code free of material from sources incompatible with this app's license (AGPL-3.0-or-later); replace code that is identical or suspiciously similar to such sources with an original implementation. For license headers see HowToApplyALicense.md; every new file needs an SPDX header or a
REUSE.tomlentry (CI runs REUSE lint).
- Act on its own. Every issue, pull request and comment is posted on behalf of a contributor who directed the agent and is accountable for it.
- Add
Signed-off-bytags. Only humans can certify the Developer Certificate of Origin. - Submit security reports. They are always submitted by a human, verified independently first, and go to HackerOne, not public issues.
- Fully automate the resolution of issues labeled
good first issueor similar beginner-friendly labels. - Submit large AI code blobs without meaningful oversight, code that has never been executed, or changes that shift debugging and cleanup work onto maintainers.
- Edit
l10n/. Translations go through Transifex.
The app must be cloned into <nextcloud>/apps/forms.
composer install # PHP dependencies, plus the tools in vendor-bin/* (phpunit, psalm, php-cs-fixer, rector, openapi-extractor)
npm ci # JS dependencies
npm run dev:watch # Frontend dev build with watch (README's `npm run watch` does not exist)npm run build # Production build into js/
npm run dev # Development build
make appstore # App store tarball (expects built js/ and vendor/)composer cs:check # PHP coding standards check
composer cs:fix # PHP coding standards fix
composer lint # PHP syntax check
composer psalm # PHP static analysis
composer rector # Rector refactorings
npm run lint # ESLint (JS/TS/Vue)
npm run lint:fix # ESLint auto-fix
npm run stylelint # SCSS/Vue style linting
npm run format # Prettier check (format:fix to write)
npm run typecheck # vue-tsccomposer test:unit # PHP unit tests
composer test:integration # PHP integration tests
npm run playwright # Playwright E2E testsBoth PHPUnit suites bootstrap a real Nextcloud (tests/bootstrap.php requires ../../../lib/base.php), so they only run from inside a server checkout with the app enabled. The integration suite also needs the server reachable at http://localhost:8080 (CI uses php -S localhost:8080): tests/Integration/Api/ApiV3Test.php makes real HTTP calls to the OCS API.
Playwright starts a Nextcloud Docker container on port 8089 (branch stable<max-version> from info.xml) via npm run start:nextcloud and tests the current js/, so build first. Specs are in playwright/e2e/, page objects in playwright/support/sections/, fixtures in playwright/support/fixtures/.
There are no frontend unit tests.
To run a single PHP test:
composer test:unit -- --filter testMethodName tests/Unit/Service/SubmissionServiceTest.phpcomposer openapi # Regenerate openapi.json from controller attributes and docblockslib/Controller/—ApiControllerandShareApiControllerareOCSControllers exposing the REST API under/ocs/v2.php/apps/forms/api/v3/….PageControllerserves the HTML shells and provides initial state.ConfigControllerhandles the admin settings.lib/Service/— Business logic.FormsServiceowns permissions, access and sharing decisions;SubmissionServicevalidates and stores answers and builds CSV/XLSX exports;ConfirmationEmailService,CirclesServiceandUploadedFilesShareServicecover their integrations.lib/Db/— Entity + mapper pairs: Form, Question, Option, Share, Submission, Answer, UploadedFile.lib/Migration/— Schema migrations namedVersion<MMmmpp>Date<YYYYMMDDHHMMSS>.lib/Middleware/—ThrottleFormAccessMiddlewarerate-limits access to public forms.lib/Events/+lib/Listener/—FormSubmittedEvent(exposed to webhooks); listeners for user deletion, Analytics datasource and comments.lib/BackgroundJob/— Confirmation mails, linked-file sync (SyncSubmissionsWithLinkedFileJob), upload cleanup, user-deletion cleanup.lib/Constants.php— Question types,extraSettingswhitelists, string length limits and other shared constants.lib/ResponseDefinitions.php— Psalm array shapes for API responses; feedsopenapi.json.
Routes are attribute-based (#[ApiRoute], #[FrontpageRoute]); there is no appinfo/routes.php. Listeners and middleware are registered in lib/AppInfo/Application.php; activity, admin settings and background jobs in appinfo/info.xml.
Built with Vue 3, Vue Router and Vite, without a store library. Entry points are defined in vite.config.js:
main— the logged-in app:src/Forms.vue+src/router.ts, viewsCreate,Submit,ResultsandSidebarinsrc/views/.submit— the public link-share and embedded submission page (src/FormsSubmit.vue).settings— admin settings (src/FormsSettings.vue).emptyContent— empty state page.
Server data arrives via @nextcloud/initial-state keys provided in PageController; API responses are unwrapped with src/utils/OcsResponse2Data.ts. Entity types are hand-written in src/types/Entities.d.ts. Question components live in src/components/Questions/, shared question behaviour in src/composables/, results rendering in src/components/Results/.
CI runs the PHP tests against SQLite, MySQL, MariaDB, PostgreSQL and Oracle, so queries and migrations must be portable across all five.
The v3 API is a public contract. openapi.json is generated — never edit it by hand. The human-readable documentation is docs/API_v3.md and docs/DataStructure.md; update them together with openapi.json whenever API behaviour changes.
-
All commits must be signed off (
git commit -s) by the human contributor per the Developer Certificate of Origin (DCO), using their real name. PRs targetmain. -
Commit messages must follow the Conventional Commits v1.0.0 specification, in this repository's form
type(scope): lowercase description, e.g.fix(submission): only accept a list of values as an answer,feat(grid): …. The message body explains why the change was made. -
CI rejects
fixup!andsquash!commits; squash them before the PR is merged. -
Every commit made with AI assistance must include the
Assisted-bytrailer mandated by the AI Contribution Policy:Assisted-by: ClaudeCode:claude-opus-5-5General pattern:
Assisted-by: AGENT_NAME:MODEL_VERSION.
- This repository has no pull request template of its own; use the Nextcloud org-wide template and keep its sections and checklist intact.
- After writing or modifying PHP code, run
composer cs:fix,composer psalmandcomposer lintbefore considering the task complete. - After writing or modifying frontend code, run
npm run lint,npm run stylelint,npm run typecheckandnpm run build. - Use
t('forms', …)/n('forms', …)for user-facing frontend strings andIL10Nin PHP.
Adding or changing a question type means changing both sides:
- Backend:
lib/Constants.php(ANSWER_TYPE_*,ANSWER_TYPES,ANSWER_TYPES_PREDEFINED, and theEXTRA_SETTINGS_*whitelist for that type'sextraSettings) plus the per-type branches inSubmissionService::validateSubmission()and answer storage. - Frontend:
src/models/AnswerTypes.ts, which maps each type to its component, labels and icons. Several types share a component (multiple/multiple_unique,date/datetime/time).
Run composer openapi and commit the result after adding, removing or renaming a route, changing a controller method signature or its @param/@return docblock, or changing a shape in lib/ResponseDefinitions.php. CI fails if openapi.json is stale.
Endpoints reachable without login carry #[PublicPage] and are protected with #[BruteForceProtection] and #[UserRateLimit]/#[AnonRateLimit]; see the submission endpoints in ApiController. A change to submission or form access must work for logged-in users, public share links and embedded forms alike.
A new migration only runs after <version> in appinfo/info.xml is bumped. The class name encodes the app version it ships in (Version050500… = 5.5.0) plus a date stamp.
Workflows in .github/workflows/ are synced from the Nextcloud organization templates. Local deviations go in the matching *.yml.patch file, never directly in the workflow.