ioBroker Copilot Instructions

A comprehensive template and best practices library for using GitHub Copilot in ioBroker adapter development

🎯 About This Repository

This repository serves the ioBroker community by providing standardized GitHub Copilot instructions for adapter development. We maintain templates and best practices to help developers create better ioBroker adapters more efficiently.

What this template provides:

• Standardized patterns for consistent ioBroker adapter development
• Proven best practices from experienced community developers
• GitHub Copilot integration that understands ioBroker conventions
• Community-driven improvements based on real-world usage
• Version-controlled templates with automated updates

🤝 Join Our Community

Help us improve ioBroker adapter development together!

• ioBroker Community Forum - Share experiences and collaborate on improving adapter development
• Submit Issues - Report bugs, suggest improvements, or request new features
• GitHub Discussions - Share ideas, ask questions, and collaborate on best practices

Your contributions help make adapter development better for the entire ioBroker community!

🚀 What is ioBroker?

ioBroker is a powerful integration platform for the Internet of Things (IoT), designed to connect various smart home devices, services, and systems into a unified automation platform. Adapters are the core components that enable ioBroker to communicate with different technologies and services.

📋 Quick Start

🚀 Fully Automated Setup (Recommended for all users):

For New Repositories or Comprehensive Setup

1. Create an automated setup issue with this simple content:

   Title: 🤖 Setup ioBroker GitHub Copilot Instructions
   
   GitHub Copilot: Please help me set up GitHub Copilot instructions for my ioBroker adapter repository using the centralized automation template from:
   https://raw.githubusercontent.com/DrozmotiX/ioBroker-Copilot-Instructions/main/templates/initial-setup-automation.md
   

2. Assign the created issue to @copilot

3. Let GitHub Copilot handle everything using our centralized automation system:

   • ✅ Validates existing setup and detects repository status
   • 📥 Downloads and customizes latest template using metadata.json
   • 🎯 Adds adapter-specific content with intelligent customization
   • ⚙️ Sets up weekly monitoring with centralized GitHub Action
   • 🛡️ Preserves any existing customizations automatically
   • 🚫 Avoids manual scripts (replaces approaches like validation scripts in package.json)

4. Copilot will create a new PR containing the required changes. Wait until Copilot finishes updating this PR and perform a review when requested by Copilot.

For Quick Updates Only

1. Create a quick update issue with this simple content:

   Title: 🤖 Update ioBroker Copilot Instructions Template
   
   GitHub Copilot: Please help me update my ioBroker Copilot instructions using the template from:
   https://raw.githubusercontent.com/DrozmotiX/ioBroker-Copilot-Instructions/main/templates/copy-paste-template.md
   

2. Assign the created issue to @copilot
3. GitHub Copilot will merge the latest template while preserving your customizations

📚 Documentation

🛠️ For Developers

• Setup Guide - Automated GitHub Copilot setup and template integration
• Automated Templates - Complete guide to all automation templates
• Testing Guide - Validate your template integration and Copilot functionality

🔧 For Repository Maintainers

• Maintenance Guide - Version management, testing infrastructure, and release processes
• Technical Testing - Detailed testing infrastructure documentation (54+ automated tests)

🔄 Automated Template Management

⚡ Zero Manual Steps Required

All template operations are now fully automated:

• ✅ Setup: Automated via Initial Setup Template
• 🔄 Updates: Automated via GitHub Actions with issue creation
• 🛡️ Customizations: Always preserved during updates
• 📅 Monitoring: Weekly checks with automatic notifications

Automated Continuous Monitoring

The Initial Setup Template automatically configures:

• 📅 Weekly version checking via GitHub Actions
• 🎯 Automatic issue creation when updates are available
• 🛡️ Safe updates that preserve all custom content
• 🚫 Prevention of duplicate update issues

💡 Key Features

⚡ Full Automation

• Zero Manual Configuration: All setup handled by GitHub Copilot
• Smart Detection: Automatically detects existing setups and customizations
• Safe Updates: Custom content always preserved during template updates

🛡️ Customization Protection

• [CUSTOMIZE] Sections: Marked areas that are automatically preserved
• Adapter-Specific Content: Automatically added based on your repository context
• Version Tracking: Automatic version management and source references

📅 Continuous Monitoring

• Weekly Checks: GitHub Actions monitor for template updates
• Automatic Issues: Update notifications created automatically
• No Maintenance: Set once, works forever

🎯 Enhanced Development

• ioBroker-Specific Suggestions: Context-aware code completion
• Best Practices: Integrated patterns from experienced developers
• Testing Integration: Smart suggestions for @iobroker/testing framework

📊 Version Information

• Current Template Version:
• Template Location: template.md

Your template version is automatically tracked in your .github/copilot-instructions.md file:

**Version:** 0.5.7
**Template Source:** https://github.com/DrozmotiX/ioBroker-Copilot-Instructions

📚 What's Included in the Template

The Copilot instruction template covers comprehensive guidance for:

🧪 Testing Guidelines

• Unit testing with Jest framework
• Official @iobroker/testing framework - Complete integration testing patterns following official guidelines
• Mocking strategies for ioBroker adapters
• Error handling test scenarios
• API testing with credentials - Password encryption and demo credential patterns
• Enhanced test failure handling - Clear, actionable error messages for debugging
• CI/CD integration - Separate jobs for credential-based API testing

🎨 Code Quality & Linting

• ESLint configuration - Using official @iobroker/eslint-config package
• Lint-first CI/CD workflow - ESLint checks run before any other tests
• Best practices - Common issues, fixes, and coding standards
• Auto-fix capabilities - Guidance on using ESLint's automatic fixes
• Workflow dependencies - Ensuring all tests depend on passing lint checks

📖 README Standards

• Required documentation sections for ioBroker adapters
• Multi-language support guidelines
• Configuration documentation patterns
• User-friendly examples and usage instructions
• Mandatory PR documentation - WORK IN PROGRESS section requirements
• Standardized changelog format - Consistent categorization and user-focused descriptions

📦 Dependency Management

• Best practices for npm package management
• Security and audit guidelines
• Preferred libraries and alternatives for ioBroker ecosystem
• Version management strategies

⚙️ JSON-Config Admin Interface

• Modern admin interface development patterns
• Configuration schema patterns
• Validation and error handling
• User experience guidelines

🌐 Translation Management

• Translation synchronization - Keep admin/i18n files aligned with jsonConfig.json
• Validation scripts - Automatic detection of orphaned and missing translation keys
• Multi-language support - Best practices for maintaining 11 language translations
• Common pitfalls - Lessons learned from real-world adapter development
• Workflow guidelines - Step-by-step process for translation updates

🔧 Best Practices

• Preference for native Node.js APIs (like fetch over axios)
• Minimal dependency strategies
• Performance considerations
• Security best practices for ioBroker adapters

🤝 How This Enhances ioBroker Development

By integrating GitHub Copilot with these specialized instructions, ioBroker adapter developers benefit from:

• Context-aware suggestions specific to ioBroker development patterns
• Consistent code style across the ioBroker ecosystem
• Best practice enforcement through AI-guided development
• Reduced development time with intelligent code completion
• Knowledge transfer from experienced to new developers
• Quality assurance through established patterns and practices

🔧 Advanced Usage

For advanced users who want more control over the template management process:

Manual Version Check

For repository diagnostics or manual validation:

# Download and run the version check script
curl -s https://raw.githubusercontent.com/DrozmotiX/ioBroker-Copilot-Instructions/main/scripts/check-template-version.sh | bash

This script will:

• Compare your local template version with the latest available from metadata.json
• Provide update guidance if your template is outdated
• Show you what's changed in newer versions

Note: The centralized automation system eliminates the need for manual template update/version-check scripts in your repository. Adapter-level quality checks (like translation validation, linting, or testing) should still be added to package.json as needed.

Repository Maintenance

For repository maintainers who want to contribute or customize the template system:

• Version Management: See the maintenance guide for version management scripts
• Testing: Run ./tests/test-runner.sh for comprehensive testing
• Custom Snippets: Create reusable content in the snippets/ directory
• Centralized Configuration: Modify config/metadata.json for repository-wide settings

🌟 Contributing

We welcome contributions to improve these instructions! Please:

1. Fork this repository
2. Create a feature branch
3. Make your improvements
4. Run the test suite: ./tests/test-runner.sh to ensure all tests pass
5. Update documentation: Add changelog entries and update README if needed
6. Test with real ioBroker adapter development
7. Submit a pull request with a clear description of changes

For maintainers: See the maintenance guide for detailed development guidelines and testing requirements.

🙏 Acknowledgments

• @ticaki - For providing comprehensive lessons learned and best practices for ioBroker integration testing framework
• ioBroker Community - For continuous feedback and real-world testing scenarios
• GitHub Copilot Team - For enabling AI-powered development assistance

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Links

• ioBroker Official Website
• ioBroker GitHub Organization
• ioBroker Developer Documentation
• GitHub Copilot Documentation

💬 Support

• Issues: Report bugs or request features in GitHub Issues
• Discussions: Join conversations in GitHub Discussions
• ioBroker Community: Visit the ioBroker Forum