AI Agent Guidelines for ownCloud Core

This file provides context for AI coding agents (Claude Code, GitHub Copilot, Cursor, etc.) working in this repository.

Repository Overview

• Product family: Classic (OC10)
• Primary language(s): PHP, JavaScript
• Build system: Composer, Make, npm/Yarn
• Test framework: PHPUnit, JavaScript tests (Node), Acceptance tests (Behat)
• CI system: GitHub Actions

Architecture & Key Paths

• lib/ - Core PHP library (private and public APIs)
• core/ - Core app (login, file list, etc.)
• apps/ - Bundled apps
• config/ - Configuration samples and defaults
• ocs/ - OCS API endpoints
• ocs-provider/ - OCS provider discovery
• ocm-provider/ - Open Cloud Mesh provider
• build/ - Build scripts and tools
• l10n/ - Translations
• tests/ - Test suites (unit, integration, acceptance)
• Makefile - Build and test automation
• composer.json - PHP dependencies
• phpcs.xml - PHP_CodeSniffer configuration
• phpstan.neon - PHPStan configuration
• CHANGELOG.md - Release history
• console.php - CLI entry point
• occ - ownCloud console CLI tool
• cron.php - Background job runner
• index.php - Web entry point

Development Conventions

• Branching: master
• Commit messages: DCO sign-off required (git commit -s). Must follow Conventional Commits format.
• Code style: PHP_CodeSniffer (phpcs.xml), ownCloud coding standard
• PR process: Open a PR against master. All CI checks must pass.

Build & Test Commands

# Build (install all dependencies)
make

# Test (PHP unit)
make test-php-unit

# Test (JavaScript)
make test-js

# Test (acceptance - API)
make test-acceptance-api

# Test (acceptance - CLI)
make test-acceptance-cli

# Test (acceptance - Web User Interface)
make test-acceptance-webui

# Lint (PHP)
make test-php-style

# Fix code style
make test-php-style-fix

Important Constraints

• All code contributions must be compatible with the AGPL-3.0 license
• Do not introduce new copyleft-licensed dependencies (GPL, AGPL, LGPL, MPL) without explicit discussion in an issue first. This is especially important for repos migrating to Apache 2.0.
• Do not introduce new dependencies without discussion in an issue first
• Conventional Commits are enforced by CI
• Translations must be submitted via Transifex, not as PRs
• This is a large, complex codebase with many interdependencies

OSPO Policy Constraints

GitHub Actions

• Only use actions owned by owncloud, created by GitHub (actions/*), verified on the GitHub Marketplace, or verified by the ownCloud Maintainers.
• Pin all actions to their full commit SHA (not tags): uses: actions/checkout@<SHA> # vX.Y.Z
• Never introduce actions from unverified third parties.

Dependency Management

• Dependabot is configured for automated dependency updates.
• Review and merge Dependabot PRs as part of regular maintenance.
• Do not introduce new dependencies without discussion in an issue first.

Git Workflow

• Rebase policy: Always rebase; never create merge commits. Use git pull --rebase and git rebase before pushing.
• Signed commits: All commits must be PGP/GPG signed (git commit -S -s).
• DCO sign-off: Every commit needs a Signed-off-by line (git commit -s).
• Conventional Commits & Squash Merge: Use the Conventional Commits format where the repository enforces it. Many repos use squash merge, where the PR title becomes the commit message on the default branch — apply Conventional Commits format to PR titles as well. A reusable GitHub Actions workflow enforces this.

Context for AI Agents

• Match existing code style
• Do not refactor unrelated code in the same PR
• Write tests for new functionality
• Keep PRs focused and atomic
• Use Conventional Commits format for all commit messages
• Be aware of the public API surface (OCP namespace) - breaking changes require careful consideration
• The lib/private/ directory contains internal APIs; lib/public/ contains the stable public API