Add comprehensive GitHub Copilot instructions for Nextcloud Maps development

[Copilot]

This PR adds comprehensive .github/copilot-instructions.md file that provides GitHub Copilot coding agents with detailed guidance on how to work effectively in the Nextcloud Maps codebase.

What's included

The instructions cover all essential aspects of working with this codebase:

Build System & Timing:

• Exact commands with validated timing: make (4-5min), npm ci (45-80s), npm run build (60-70s)
• Critical "NEVER CANCEL" warnings with appropriate timeout recommendations (5-10+ minutes)
• Clean rebuild procedures with make distclean && make (2-3min total)
• Development workflow with make dev for faster incremental builds

Code Quality & Validation:

• All linting tools with expected behavior: npm run lint (~2500 issues expected), composer run cs:check (should pass)
• Validation requirements for CI compatibility
• PHP static analysis limitations and workarounds

Project Structure:

• Frontend: Vue.js components, Vuex store, webpack build system
• Backend: PHP controllers, services, database layers, CLI commands
• Key file locations for common development tasks

Environment & Dependencies:

• Node.js version compatibility (22+ preferred, 20+ works with warnings)
• PHP requirements (8.1-8.4) and Nextcloud context (30-31)
• Composer authentication issues and automatic fallback behavior

Testing & Validation:

• Manual testing scenarios within Nextcloud environment
• Limitation: PHP tests require full Nextcloud server installation
• Build artifact management and gitignore considerations

Validation performed

All commands and timing data were thoroughly tested:

• Complete clean rebuilds from scratch
• Individual build component timing
• Linting tool behavior and output analysis
• Error scenarios and recovery procedures
• Development workflow validation

The instructions prioritize practical, working guidance that saves agents from trial-and-error discovery of build requirements and common gotchas in this complex dual-stack (PHP + Vue.js) Nextcloud application.

Fixes #1450.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• fnm.vercel.app
  • Triggering command: curl -fsSL REDACTED (dns block)
• https://api.github.com/repos/Bogdaan/open-location-code/zipball/6e384e41cc6d6dd4d87f95c36aabf0de5256bf3f
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/aek1Ng /usr/bin/composer install --prefer-dist (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/79aIY4 /usr/bin/composer install --prefer-dist --no-interaction (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/qNIwIP /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/ChristophWurst/nextcloud_testing/zipball/9c189b01dbcc3508108f08c417de6aaea7005fb0
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/PHP-CS-Fixer/shim/zipball/eea219a577085bd13ff0cb644a422c20798316c7
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/79aIY4 /usr/bin/composer install --prefer-dist --no-interaction (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/bamarni/composer-bin-plugin/zipball/92fd7b1e6e9cdae19b0d57369d8ad31a37b6a880
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/aek1Ng /usr/bin/composer install --prefer-dist (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/79aIY4 /usr/bin/composer install --prefer-dist --no-interaction (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/qNIwIP /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/doctrine/cache/zipball/1ca8f21980e770095a31456042471a57bc4c68fb
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/doctrine/dbal/zipball/ec16c82f20be1a7224e65ac67144a29199f87959
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/doctrine/deprecations/zipball/459c2f5dd3d6a4633d3b5f46ee2b1c40f57d3f38
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/doctrine/event-manager/zipball/b680156fa328f1dfd874fd48c7026c41570b9c6e
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/doctrine/instantiator/zipball/c6222283fa3f4ac679f8b9ced9a4e23f163e80d0
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/kubawerlos/php-cs-fixer-custom-fixers/zipball/93222100a91399314c3726857e249e76c4a7d760
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/79aIY4 /usr/bin/composer install --prefer-dist --no-interaction (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/myclabs/DeepCopy/zipball/024473a478be9df5fdaca2c793f2232fe788e414
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/nextcloud-deps/ocp/zipball/1fb984268039921920ade298ef5a58e8fe3de7da
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/nextcloud/coding-standard/zipball/9c719c4747fa26efc12f2e8b21c14a9a75c6ba6d
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/79aIY4 /usr/bin/composer install --prefer-dist --no-interaction (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/nikic/PHP-Parser/zipball/447a020a1f875a434d62f2a401f53b82a396e494
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/pel/pel/zipball/b95fe29cdacf9d36330da277f10910a13648c84c
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/phar-io/manifest/zipball/54750ef60c58e43759730615a392c31c80e23176
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/phar-io/version/zipball/4f7fd7836c6f332bb2933569e566a0d6c4cbed74
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/php-fig/cache/zipball/aa5030cfa5405eccfdcb1083ce040c2cb8d253bf
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/php-fig/clock/zipball/e41a24703d4560fd0acb709162f73b8adfc3aa0d
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/php-fig/container/zipball/c71ecc56dfe541dbd90c5360474fbc405f8d5963
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/php-fig/event-dispatcher/zipball/dbefd12671e8a14ec7f180cab83036ed26714bb0
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/php-fig/log/zipball/f16e1d5863e37f8d8c2a01719f5b34baa2b714d3
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/php-webdriver/php-webdriver/zipball/998e499b786805568deaf8cbf06f4044f05d91bf
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/psalm/phar/zipball/abb4e050e24d6cc3ac9264e32b0f23acba2d00fb
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sabre-io/event/zipball/86d57e305c272898ba3c28e9bd3d65d5464587c2
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sabre-io/uri/zipball/b76524c22de90d80ca73143680a8e77b1266c291
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sabre-io/vobject/zipball/ff22611a53782e90c97be0d0bc4a5f98a5c0a12c
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sabre-io/xml/zipball/01a7927842abf3e10df3d9c2d9b0cc9d813a3fcc
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/cli-parser/zipball/2b56bea83a09de3ac06bb18b92f068e60cc6f50b
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/code-unit-reverse-lookup/zipball/ac91f01ccec49fb77bdc6fd1e548bc70f7faa3e5
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/code-unit/zipball/1fc9f64c0927627ef78ba436c9b17d967e68e120
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/comparator/zipball/fa0f136dd2334583309d32b62544682ee972b51a
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/complexity/zipball/25f207c40d62b8b7aa32f5ab026c53561964053a
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/diff/zipball/ba01945089c3a293b01ba9badc29ad55b106b0bc
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/environment/zipball/830c43a844f1f8d5b7a1f6d6076b784454d8b7ed
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/exporter/zipball/78c00df8f170e02473b682df15bfcdacc3d32d72
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/global-state/zipball/bca7df1f32ee6fe93b4d4a9abbf69e13a4ada2c9
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/lines-of-code/zipball/e1e4a170560925c26d424b6a03aed157e7dcc5c5
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/object-enumerator/zipball/5c9eeac41b290a3712d88851518825ad78f45c71
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/aek1Ng /usr/bin/composer install --prefer-dist (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/79aIY4 /usr/bin/composer install --prefer-dist --no-interaction (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/qNIwIP /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/object-reflector/zipball/b4f479ebdbf63ac605d183ece17d8d7fe49c15c7
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/79aIY4 /usr/bin/composer install --prefer-dist --no-interaction (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/qNIwIP /usr/bin/composer install --prefer-dist (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/php-code-coverage/zipball/85402a822d1ecf1db1096959413d35e1c37cf1a5
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/php-file-iterator/zipball/cf1c2e7c203ac650e352f4cc675a7021e7d1b3cf
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/php-invoker/zipball/5a10147d0aaf65b58940a0b72f71c9ac0423cc67
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/php-text-template/zipball/5da5f67fc95621df9ff4c4e5a84d6a8a2acf7c28
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/php-timer/zipball/5a63ce20ed1b5bf577850e2c4e87f4aa902afbd2
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/phpunit/zipball/f80235cb4d3caa59ae09be3adf1ded27521d1a9c
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/recursion-context/zipball/e75bd0f07204fec2a0af9b0f3cfe97d05f92efc1
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/79aIY4 /usr/bin/composer install --prefer-dist --no-interaction (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/qNIwIP /usr/bin/composer install --prefer-dist (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/resource-operations/zipball/05d5692a7993ecccd56a03e40cd7e5b09b1d404e
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/79aIY4 /usr/bin/composer install --prefer-dist --no-interaction (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/qNIwIP /usr/bin/composer install --prefer-dist (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/type/zipball/75e2c2a32f5e0b3aef905b9ed0b179b953b3d7c7
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/aek1Ng /usr/bin/composer install --prefer-dist (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/79aIY4 /usr/bin/composer install --prefer-dist --no-interaction (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/qNIwIP /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/sebastianbergmann/version/zipball/c6c1022351a901512170118436c764e473f6de8c
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/aek1Ng /usr/bin/composer install --prefer-dist (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/79aIY4 /usr/bin/composer install --prefer-dist --no-interaction (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/qNIwIP /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/symfony/console/zipball/e51498ea18570c062e7df29d05a7003585b19b88
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/symfony/deprecation-contracts/zipball/74c71c939a79f7d5bf3c1ce9f5ea37ba0114c6f6
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/symfony/polyfill-mbstring/zipball/85181ba99b2345b0ef10ce42ecac37612d9fd341
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/symfony/process/zipball/87b7c93e57df9d8e39a093d32587702380ff045d
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/symfony/service-contracts/zipball/e53260aabf78fb3d63f8d79d69ece59f80d5eda0
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/symfony/string/zipball/446e0d146f991dde3e73f45f2c97a9faad773c82
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/oPjq0y /usr/bin/composer install --prefer-dist (http block)
• https://api.github.com/repos/theseer/tokenizer/zipball/737eda637ed5e28c3413cb1ebe8bb52cbf1ca7a2
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/VwLvIi /usr/bin/composer install --prefer-dist (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.