This PR adds a comprehensive .github/copilot-instructions.md file that provides GitHub Copilot coding agents with detailed instructions for working effectively in the gocron codebase.

What's Included

The instructions cover all essential development workflows:

• Bootstrap and Build: Complete setup commands including dependency installation, tool requirements, and build validation
• Testing: Comprehensive testing commands with proper timeout warnings (tests take ~50 seconds and require 90+ second timeouts)
• Linting: Primary linting via make lint plus fallback alternatives due to golangci-lint config compatibility issues
• Validation Scenarios: Manual testing approaches including a working example script that validates basic scheduler functionality
• Repository Structure: Complete overview of key files and directories
• Troubleshooting: Common issues and solutions including tool installation, PATH configuration, and timing expectations

Key Features

• Exhaustive Validation: Every command and instruction has been tested and validated to work correctly
• Timeout Guidance: Explicit "NEVER CANCEL" warnings with specific timeout recommendations for long-running operations
• Working Examples: Includes a validated example script that agents can use to test basic functionality
• Tool Requirements: Documents exact tool installation commands (mockgen, golangci-lint) with version considerations
• Known Issues: Transparent documentation of golangci-lint config compatibility issues with workarounds

Example Usage

The instructions include a validated example script:

s, err := gocron.NewScheduler()
j, err := s.NewJob(
    gocron.DurationJob(2*time.Second),
    gocron.NewTask(func() { fmt.Println("Working!") }),
)
s.Start()
time.Sleep(6 * time.Second)
s.Shutdown()

This ensures agents can quickly validate their changes work with the core library functionality.

Timing Information

All commands include measured timing data:

• Tests: ~50 seconds (requires 90+ second timeouts)
• Build: ~5 seconds
• Mock generation: ~2 seconds
• Coverage: 93.8% expected

The instructions emphasize the critical importance of never canceling long-running test operations, as this is a common source of CI failures.

Fixes #865.

💡 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.