Add comprehensive GitHub Copilot instructions with header organization and conventional commits requirements for EICrecon development

[Copilot]

This PR adds a comprehensive .github/copilot-instructions.md file that provides GitHub Copilot with detailed instructions for working effectively in the EICrecon codebase, including critical header organization requirements for IWYU compliance and conventional commit standards for breaking change identification.

Key Features

Primary Development Environment: The instructions emphasize using eic-shell as the only recommended development approach, with step-by-step setup commands:

mkdir ~/eic
cd ~/eic
curl --location https://get.epic-eic.org | bash
./eic-shell
source /opt/detector/epic-main/bin/thisepic.sh

Critical Timing Warnings: Given EICrecon's complex physics dependencies, the instructions include explicit timing expectations and "NEVER CANCEL" warnings:

• Build times: 30-60 minutes (90+ minute timeout recommended)
• Test suite: 15-30 minutes (45+ minute timeout recommended)
• Manual dependency builds: 4-8 hours (not recommended)

Code Style and Header Organization: Comprehensive requirements for header management to pass include-what-you-use (IWYU) checks:

1. Alphabetical ordering within each blank-line delimited header block
2. Include syntax rules: angle brackets <> for system/third-party headers, quotes "" for project headers
3. Proper grouping: system headers, third-party headers, then project headers

#include <algorithm>
#include <memory>
#include <vector>

#include <DD4hep/Detector.h>
#include <JANA/JApplication.h>
#include <edm4eic/ClusterCollection.h>

#include "algorithms/calorimetry/CalorimeterHitDigi.h"
#include "services/geometry/dd4hep/DD4hep_service.h"

Conventional Commits and Breaking Changes: Instructions for following the Conventional Commits specification with EICrecon-specific guidance on what constitutes breaking changes:

• Command-line interface changes: Removal/renaming of eicrecon options, parameter modifications
• Output collection changes: Renaming collections like EcalBarrelClusters, removing user-dependent collections

feat!: change ECAL cluster collection name for consistency

BREAKING CHANGE: EcalBarrelClusters collection renamed to ECALBarrelClusters
to match naming convention. Update analysis scripts to use new name.

Validated Build Commands: All commands are extracted from official documentation and CI workflows:

cmake -B build -S . -DCMAKE_INSTALL_PREFIX=install
cmake --build build --target install -- -j8
source install/bin/eicrecon-this.sh

Manual Validation Scenarios: Step-by-step validation procedures that Copilot should execute after making changes:

• Basic executable tests (eicrecon --help, eicrecon --version)
• Plugin validation (eicrecon -Pplugins=podio,dd4hep)
• Environment verification (library paths, dependencies)

Repository Navigation: Detailed guidance on key directories and commonly modified files:

• src/algorithms/ - Core physics algorithms
• src/factories/ - JANA factory implementations
• src/tests/ - Unit and integration tests with specific test suites

Development Workflows: Instructions for incremental builds, testing specific components, and integration with the CI system that includes multiple compilers, sanitizers, and physics validation tests.

Manual Build Warnings: Clear documentation that manual dependency installation is extremely complex (requiring JANA, ROOT, DD4hep, ACTS, etc.) and strongly discouraged in favor of eic-shell.

The instructions follow the required format with a firm directive to always follow these instructions first, only falling back to additional search if the information is incomplete or incorrect.

Fixes #2027.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

@wdconinc 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.

I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.

[wdconinc]

@copilot Is this ready for review?

[Copilot]

@copilot Is this ready for review?

Yes, this is ready for review. I've addressed the formatting issues and ensured all commands are correct. The comprehensive instructions cover eic-shell setup, build processes, timing warnings, validation scenarios, and development workflows as required for EICrecon development.

[wdconinc]

@veprbl Can you give this a review? "Only users who did not collaborate with Copilot will satisfy review requirements."

[github-actions]

Capybara summary for PR 2028

• rec_dis_10x100_minQ2=0_craterlake_10x100
• rec_dis_10x100_minQ2=1000_craterlake_tracking_only
• rec_dis_18x275_minQ2=0_craterlake_18x275
• rec_dis_18x275_minQ2=0_craterlake_18x275_MT
• rec_dis_18x275_minQ2=0_craterlake_18x275_ST_MT
• rec_dis_18x275_minQ2=1000_craterlake_18x275
• rec_dis_18x275_minQ2=1000_craterlake_18x275_MT
• rec_dis_18x275_minQ2=1000_craterlake_18x275_ST_MT
• rec_dis_5x41_minQ2=0_craterlake_5x41
• rec_e_1GeV_20GeV_craterlake
• rec_pi_1GeV_20GeV_craterlake
  ^{_{Last updated 2025-08-22T15:11-04:00 a39768c}}

[wdconinc]

@copilot Add to these GitHub Copilot instructions the necessary AI instructions to ensure that headers will be sorted alphabetically within each blank-line delimited header block, such that they are more likely to pass the include-what-you-use checks that verify alphabetic header ordering.

[Copilot]

@copilot Add to these GitHub Copilot instructions the necessary AI instructions to ensure that headers will be sorted alphabetically within each blank-line delimited header block, such that they are m...

Added comprehensive header alphabetization requirements in commit 88897cc. The instructions now specify that headers must be sorted alphabetically within each blank-line delimited header block to pass IWYU checks, including proper grouping (system, third-party, project headers) and examples of correct ordering.

[wdconinc]

@copilot Add to these GitHub Copilot instructions the necessary AI instructions to ensure that local header includes will use quotes and external dependency header includes will use angle brackets.

[wdconinc]

@copilot Add to these GitHub Copilot instructions the necessary AI instructions to ensure that pull requests follow the conventional commit specification at https://www.conventionalcommits.org/en/v1.0.0/, so as to clearly highlight breaking changes. Consider within the scope of breaking changes:

• any scripts in which users may call eicrecon with command line arguments, and which should continue to behave as before,
• the names of output collections that users my use in analysis, and which should continue to exist with substantially similar content (even if developments in algorithms causes the exact content to be different).

[Copilot]

@copilot Add to these GitHub Copilot instructions the necessary AI instructions to ensure that local header includes will use quotes and external dependency header includes will use angle brackets.

Added explicit instructions for header include syntax in commit df0b26e. The instructions now specify that angle brackets <> should be used for system/standard library headers and external dependencies, while quotes "" should be used for project-specific/local headers. This is included both in the main header organization rules and emphasized in the "When editing existing code" section.

[Copilot]

@copilot Add to these GitHub Copilot instructions the necessary AI instructions to ensure that pull requests follow the conventional commit specification at https://www.conventionalcommits.org/en/v1.0...

Added comprehensive conventional commits requirements in commit fdf02d0. The instructions now include:

• Standard commit message format following conventionalcommits.org specification
• EICrecon-specific breaking change definitions for CLI arguments and output collections
• Examples of proper breaking change commit messages with BREAKING CHANGE: footers
• Validation commands for testing compatibility before marking changes as breaking

This ensures clear identification of changes that affect user scripts calling eicrecon or analysis code using output collection names.