From d96d41274719c0c0ac87128943198b6265a7f547 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Sep 2025 21:57:25 +0000 Subject: [PATCH 01/10] Initial plan From 0809cbaa0e07b0d1c36fb2a5e1ba0fff2131941c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Sep 2025 22:06:48 +0000 Subject: [PATCH 02/10] Separate README into focused documentation files by instruction type Co-authored-by: DutchmanNL <7318445+DutchmanNL@users.noreply.github.com> --- README.md | 328 ++++++-------------------------------------- docs/maintenance.md | 225 ++++++++++++++++++++++++++++++ docs/setup.md | 221 +++++++++++++++++++++++++++++ docs/testing.md | 231 +++++++++++++++++++++++++++++++ 4 files changed, 716 insertions(+), 289 deletions(-) create mode 100644 docs/maintenance.md create mode 100644 docs/setup.md create mode 100644 docs/testing.md diff --git a/README.md b/README.md index 7ad4b14..776da65 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # ioBroker Copilot Instructions -> A track & traceable library of best practices for using GitHub Copilot to support ioBroker adapter development +> A comprehensive template and best practices library for using GitHub Copilot in ioBroker adapter development ## ๐ŸŽฏ Goal of this Repository @@ -16,206 +16,38 @@ This repository provides comprehensive guidance and best practices for leveragin [ioBroker](https://www.iobroker.net/) 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. -## Prerequisites and Basic GitHub Copilot Setup +## ๐Ÿ“‹ Quick Start -Before using this template, ensure you have GitHub Copilot properly set up in your repository. If you're new to GitHub Copilot, follow these steps: +> **New to GitHub Copilot?** Start with the [detailed setup guide](docs/setup.md) to get GitHub Copilot working in your repository first. -### Step 1: GitHub Copilot Subscription & Installation +**For experienced Copilot users:** -1. **Subscribe to GitHub Copilot** - - Visit [GitHub Copilot](https://github.com/features/copilot) and subscribe to GitHub Copilot Individual or Business - - Ensure your subscription is active and includes your target repository +1. **Download the template**: Get the latest [`template.md`](template.md) +2. **Integrate**: Save as `.github/copilot-instructions.md` in your adapter repository +3. **Customize**: Modify sections marked with `[CUSTOMIZE]` +4. **Verify**: Test that Copilot provides ioBroker-specific suggestions -2. **Install GitHub Copilot Extension** - - **VS Code**: Install the [GitHub Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) - - **JetBrains IDEs**: Install GitHub Copilot from the plugin marketplace - - **Vim/Neovim**: Use the [copilot.vim](https://github.com/github/copilot.vim) plugin - - **Other editors**: Check [GitHub Copilot documentation](https://docs.github.com/en/copilot) for your editor +**Current Version:** v0.4.0 | **Template:** [`template.md`](template.md) | **Last Updated:** September 2025 -3. **Authenticate GitHub Copilot** - - Open your editor and sign in to GitHub Copilot when prompted - - Verify authentication by typing code in any file - you should see Copilot suggestions +## ๐Ÿ“š Documentation -### Step 2: Repository Setup & Validation +### ๐Ÿ› ๏ธ For Developers +- **[Setup Guide](docs/setup.md)** - Complete GitHub Copilot setup and template integration +- **[Testing Guide](docs/testing.md)** - Validate your template integration and Copilot functionality -1. **Enable Copilot for Your Repository** - ```bash - # Navigate to your ioBroker adapter repository - cd your-iobroker-adapter - - # Ensure you're logged into GitHub CLI (optional but recommended) - gh auth login - ``` +### ๐Ÿ”ง For Repository Maintainers +- **[Maintenance Guide](docs/maintenance.md)** - Version management, testing infrastructure, and release processes +- **[Technical Testing](TESTING.md)** - Detailed testing infrastructure documentation (54+ automated tests) -2. **Create Basic GitHub Copilot Structure** - ```bash - # Create .github directory if it doesn't exist - mkdir -p .github - - # Verify Copilot can access your repository - # Open any .js/.ts file and start typing - you should see suggestions - ``` +## ๐Ÿ”„ Template Versioning & Updates -3. **Verify Copilot is Working** - - Open a JavaScript or TypeScript file in your repository - - Start typing a function or comment - - You should see grayed-out suggestions from Copilot - - Press `Tab` to accept suggestions or `Esc` to dismiss +### Quick Version Check -### Step 3: Test Basic Functionality - -Create a simple test to verify Copilot is working with your repository: - -```javascript -// Create a file test-copilot.js and start typing this comment: -// Function to add two numbers - -// Copilot should suggest a function implementation when you press Enter -``` - -**Expected behavior:** Copilot should suggest code completions as you type. - -### Step 4: Repository Permissions (For Organizations) - -If your repository is part of an organization: - -1. **Check Organization Settings** - - Go to your GitHub organization settings - - Navigate to "Copilot" in the left sidebar - - Ensure your repository is included in the allowed repositories - -2. **Verify Team Access** - - Ensure your team has Copilot access enabled - - Check that repository access policies allow Copilot usage - -### Troubleshooting Basic Setup - -| Problem | Solution | -|---------|----------| -| No suggestions appear | Check authentication and subscription status | -| Repository not accessible | Verify organization settings and permissions | -| Extension not working | Reinstall Copilot extension and restart editor | -| Authentication issues | Sign out and sign back in to GitHub Copilot | - -**โœ… Setup Complete!** Once you have Copilot working and showing suggestions in your repository, you can proceed to integrate the ioBroker template below. - -### Quick Reference Checklist - -For experienced GitHub Copilot users, here's a quick checklist: - -- [ ] GitHub Copilot subscription is active -- [ ] Copilot extension installed in your editor -- [ ] Authentication completed (can see suggestions when typing) -- [ ] Repository permissions configured (for organizations) -- [ ] Basic functionality tested (suggestions appear in .js/.ts files) -- [ ] Ready to integrate ioBroker template - -**New to GitHub Copilot?** Follow the detailed [Prerequisites & Basic Setup](#๐Ÿ› ๏ธ-prerequisites--basic-github-copilot-setup) above. - -## ๐Ÿ“‹ How to Use This Template - -### Quick Start - -> **โš ๏ธ Prerequisites Required:** Before proceeding, ensure you've completed the [Basic GitHub Copilot Setup](#๐Ÿ› ๏ธ-prerequisites--basic-github-copilot-setup) above. - -1. **For Existing Copilot Users (Recommended)** - - If you already have a `.github/copilot-instructions.md` file, merge the content from this template rather than replacing it - - Use GitHub Copilot to help you merge the instructions: "Merge my existing copilot instructions with the template from https://github.com/DrozmotiX/ioBroker-Copilot-Instructions maintaining project-specific context" - - Add the template version reference to track updates - -2. **For New Copilot Users** - - Download the latest version of [`template.md`](template.md) - - Save it as `.github/copilot-instructions.md` in your adapter repository's `.github/` folder - - Customize sections marked with `[CUSTOMIZE]` for your specific adapter requirements - -3. **Verification & Activation** - - Verify GitHub Copilot is working in your repository (should show suggestions when typing) - - The ioBroker-specific instructions will automatically be used by Copilot when working in your codebase - - Test by opening a JavaScript file and typing ioBroker-related code - you should see relevant suggestions - -### Integration Steps - -> **โš ๏ธ Important:** Ensure GitHub Copilot is working in your repository before proceeding. If you need setup help, see the [Prerequisites & Basic Setup](#๐Ÿ› ๏ธ-prerequisites--basic-github-copilot-setup) section above. - -**For repositories with existing Copilot instructions:** -```bash -# Navigate to your ioBroker adapter repository -cd your-iobroker-adapter - -# Verify Copilot is working (should show suggestions when you type) -# Open any .js file and type: // Function to connect to ioBroker -# You should see Copilot suggestions appear - -# Ask GitHub Copilot to merge the instructions -# Use the following prompt in your editor: -# "Merge my existing .github/copilot-instructions.md with the ioBroker template -# from https://github.com/DrozmotiX/ioBroker-Copilot-Instructions/blob/main/template.md -# Keep project-specific content and add version: 0.4.0" -# NOTE: Exclude the HTML comment block at the top of the template" -``` - -**For new repositories (first-time Copilot setup):** -```bash -# Navigate to your ioBroker adapter repository -cd your-iobroker-adapter - -# Verify basic Copilot setup is complete -# Open any .js file and start typing - you should see suggestions -# If no suggestions appear, complete the basic setup first - -# Create .github directory if it doesn't exist -mkdir -p .github - -# Download the latest template -curl -o .github/copilot-instructions.md https://raw.githubusercontent.com/DrozmotiX/ioBroker-Copilot-Instructions/main/template.md - -# Remove the template comment block at the top (lines starting with $/d' .github/copilot-instructions.md - -# Commit the changes -git add .github/copilot-instructions.md -git commit -m "Add GitHub Copilot instructions for ioBroker development" -git push -``` - -### Validation & Testing - -After completing the integration, verify everything is working correctly: +Check if your template is up-to-date: ```bash -# Test that Copilot uses the ioBroker instructions -# 1. Open any .js or .ts file in your adapter -# 2. Start typing ioBroker-related code: -# Example: // Create new ioBroker adapter instance -# Example: this.setState( -# Example: // Handle device connection - -# 3. Copilot should now provide ioBroker-specific suggestions -# 4. Check that suggestions follow the patterns from the template -``` - -**Expected Results:** -- Copilot suggestions should be more relevant to ioBroker development -- Error handling should follow ioBroker patterns -- Test suggestions should include `@iobroker/testing` framework usage -- README updates should follow ioBroker documentation standards - -## ๐Ÿ”„ Template Versioning - -To ensure you're using the latest best practices and that your local copy stays synchronized with improvements: - -### Current Version -- **Latest Version:** v0.4.0 -- **Template Location:** [`template.md`](template.md) -- **Last Updated:** September 2025 - -### Version Checking - -You can validate your local template version by checking the version header in your `.github/copilot-instructions.md` file: - -```markdown -**Version:** 0.4.0 -**Template Source:** https://github.com/DrozmotiX/ioBroker-Copilot-Instructions +# Download and run the version check script +curl -s https://raw.githubusercontent.com/DrozmotiX/ioBroker-Copilot-Instructions/main/scripts/check-template-version.sh | bash ``` ### Updating Your Template @@ -228,99 +60,22 @@ To update to the latest version: 4. **Review changes** to understand what improvements were made 5. **Test** to ensure compatibility with your project -### Automated Validation - -#### Quick Version Check Script - -You can use the provided script to check your template version: - -```bash -# Download and run the version check script -curl -s https://raw.githubusercontent.com/DrozmotiX/ioBroker-Copilot-Instructions/main/scripts/check-template-version.sh | bash -``` - -#### Version Management for Repository Maintainers +### Version Information -This repository includes comprehensive version management scripts that automatically handle version consistency across all documentation: - -```bash -# Show current versions across all files -./scripts/manage-versions.sh show - -# Check for version inconsistencies -./scripts/manage-versions.sh check - -# Sync documentation with current template version (updates dates and versions dynamically) -./scripts/manage-versions.sh sync - -# Update to a new version across all files -./scripts/manage-versions.sh update 0.3.2 -``` - -These scripts ensure that: -- Version numbers are dynamically pulled from the template -- Documentation dates stay current -- All cross-references remain consistent -- Manual version updates are no longer needed - -### Automated Testing Infrastructure - -This repository includes a comprehensive automated testing framework that ensures all scripts and automations work correctly: - -```bash -# Run all tests (54 total tests) -./tests/test-runner.sh - -# Run specific test file -./tests/test-runner.sh tests/test-extract-version.sh +- **Latest Version:** v0.4.0 +- **Template Location:** [`template.md`](template.md) +- **Last Updated:** September 2025 -# Tests are automatically run in CI/CD via GitHub Actions -``` +You can validate your local template version by checking the version header in your `.github/copilot-instructions.md` file: -**Test Coverage:** -- **Unit Tests**: Individual script functions and parameter validation -- **Integration Tests**: Cross-script workflows and end-to-end scenarios -- **Error Handling Tests**: Missing files, invalid parameters, network failures -- **Consistency Tests**: Version synchronization and file state validation - -**Key Features:** -- **Isolated Test Environments**: Each test run uses temporary directories to prevent interference -- **Comprehensive Reporting**: Color-coded output with detailed error messages and debugging information -- **CI/CD Integration**: Automated testing on all repository changes via `.github/workflows/test-scripts.yml` -- **Developer Friendly**: Simple commands with clear documentation in `TESTING.md` - -All repository scripts are thoroughly tested to prevent regressions and ensure reliability for the ioBroker community. - -#### GitHub Action for Continuous Monitoring - -You can set up a GitHub Action to periodically check if your template is up-to-date: - -```yaml -# .github/workflows/check-copilot-template.yml -name: Check Copilot Template Version -on: - schedule: - - cron: '0 0 * * 0' # Weekly check - workflow_dispatch: - -jobs: - check-template: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: Check template version - run: | - CURRENT_VERSION=$(grep "Version:" .github/copilot-instructions.md | head -1 | sed 's/.*Version:\s*//') - LATEST_VERSION=$(curl -s https://raw.githubusercontent.com/DrozmotiX/ioBroker-Copilot-Instructions/main/template.md | grep "Version:" | head -1 | sed 's/.*Version:\s*//') - if [ "$CURRENT_VERSION" != "$LATEST_VERSION" ]; then - echo "Template is outdated. Current: $CURRENT_VERSION, Latest: $LATEST_VERSION" - exit 1 - fi +```markdown +**Version:** 0.4.0 +**Template Source:** https://github.com/DrozmotiX/ioBroker-Copilot-Instructions ``` -## ๐Ÿ“š What's Included +## ๐Ÿ“š What's Included in the Template -The Copilot instruction template covers: +The Copilot instruction template covers comprehensive guidance for: ### ๐Ÿงช Testing Guidelines - Unit testing with Jest framework @@ -332,7 +87,7 @@ The Copilot instruction template covers: - **CI/CD integration** - Separate jobs for credential-based API testing ### ๐Ÿ“– README Standards -- Required documentation sections +- Required documentation sections for ioBroker adapters - Multi-language support guidelines - Configuration documentation patterns - User-friendly examples and usage instructions @@ -342,22 +97,22 @@ The Copilot instruction template covers: ### ๐Ÿ“ฆ Dependency Management - Best practices for npm package management - Security and audit guidelines -- Preferred libraries and alternatives +- Preferred libraries and alternatives for ioBroker ecosystem - Version management strategies ### โš™๏ธ JSON-Config Admin Interface -- Modern admin interface development +- Modern admin interface development patterns - Configuration schema patterns - Validation and error handling - User experience guidelines -### ๐Ÿ”ง Dependency Best Practices +### ๐Ÿ”ง Best Practices - Preference for native Node.js APIs (like `fetch` over `axios`) - Minimal dependency strategies - Performance considerations -- Security best practices +- Security best practices for ioBroker adapters -## ๐Ÿค How This Supports ioBroker Development +## ๐Ÿค How This Enhances ioBroker Development By integrating GitHub Copilot with these specialized instructions, ioBroker adapter developers benefit from: @@ -373,19 +128,14 @@ By integrating GitHub Copilot with these specialized instructions, ioBroker adap We welcome contributions to improve these instructions! Please: 1. Fork this repository -2. Create a feature branch +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 -### Development Guidelines - -- All new scripts must have corresponding tests in the `tests/` directory -- Changes to existing scripts require updating relevant test cases -- Follow the testing patterns documented in `TESTING.md` -- Ensure all 54 tests pass before submitting PRs +**For maintainers**: See the [maintenance guide](docs/maintenance.md) for detailed development guidelines and testing requirements. ## ๐Ÿ™ Acknowledgments diff --git a/docs/maintenance.md b/docs/maintenance.md new file mode 100644 index 0000000..56e0926 --- /dev/null +++ b/docs/maintenance.md @@ -0,0 +1,225 @@ +# Repository Maintenance Guide + +This guide is specifically for maintainers of the ioBroker Copilot Instructions repository. It covers version management, testing infrastructure, and repository maintenance procedures. + +## ๐Ÿ“‹ Table of Contents + +- [Version Management](#version-management) +- [Automated Testing Infrastructure](#automated-testing-infrastructure) +- [Development Guidelines](#development-guidelines) +- [Release Process](#release-process) +- [Troubleshooting](#troubleshooting) + +## Version Management + +This repository includes comprehensive version management scripts that automatically handle version consistency across all documentation. + +### Available Commands + +```bash +# Show current versions across all files +./scripts/manage-versions.sh show + +# Check for version inconsistencies +./scripts/manage-versions.sh check + +# Sync documentation with current template version (updates dates and versions dynamically) +./scripts/manage-versions.sh sync + +# Update to a new version across all files +./scripts/manage-versions.sh update 0.3.2 +``` + +### What the Scripts Do + +These scripts ensure that: +- Version numbers are dynamically pulled from the template +- Documentation dates stay current +- All cross-references remain consistent +- Manual version updates are no longer needed + +### Version Check for Users + +Users can validate their local template version with our provided script: + +```bash +# Download and run the version check script +curl -s https://raw.githubusercontent.com/DrozmotiX/ioBroker-Copilot-Instructions/main/scripts/check-template-version.sh | bash +``` + +### GitHub Action for Continuous Monitoring + +You can set up a GitHub Action to periodically check if templates are up-to-date: + +```yaml +# .github/workflows/check-copilot-template.yml +name: Check Copilot Template Version +on: + schedule: + - cron: '0 0 * * 0' # Weekly check + workflow_dispatch: + +jobs: + check-template: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Check template version + run: | + CURRENT_VERSION=$(grep "Version:" .github/copilot-instructions.md | head -1 | sed 's/.*Version:\s*//') + LATEST_VERSION=$(curl -s https://raw.githubusercontent.com/DrozmotiX/ioBroker-Copilot-Instructions/main/template.md | grep "Version:" | head -1 | sed 's/.*Version:\s*//') + if [ "$CURRENT_VERSION" != "$LATEST_VERSION" ]; then + echo "Template is outdated. Current: $CURRENT_VERSION, Latest: $LATEST_VERSION" + exit 1 + fi +``` + +## Automated Testing Infrastructure + +This repository includes a comprehensive automated testing framework that ensures all scripts and automations work correctly. + +### Running Tests + +```bash +# Run all tests (54 total tests) +./tests/test-runner.sh + +# Run specific test file +./tests/test-runner.sh tests/test-extract-version.sh + +# Tests are automatically run in CI/CD via GitHub Actions +``` + +### Test Coverage + +**Unit Tests**: Individual script functions and parameter validation +**Integration Tests**: Cross-script workflows and end-to-end scenarios +**Error Handling Tests**: Missing files, invalid parameters, network failures +**Consistency Tests**: Version synchronization and file state validation + +### Key Testing Features + +- **Isolated Test Environments**: Each test run uses temporary directories to prevent interference +- **Comprehensive Reporting**: Color-coded output with detailed error messages and debugging information +- **CI/CD Integration**: Automated testing on all repository changes via `.github/workflows/test-scripts.yml` +- **Developer Friendly**: Simple commands with clear documentation in `TESTING.md` + +All repository scripts are thoroughly tested to prevent regressions and ensure reliability for the ioBroker community. + +For detailed testing documentation, see [TESTING.md](../TESTING.md). + +## Development Guidelines + +### Contributing Requirements + +- All new scripts must have corresponding tests in the `tests/` directory +- Changes to existing scripts require updating relevant test cases +- Follow the testing patterns documented in `TESTING.md` +- Ensure all 54 tests pass before submitting PRs + +### Code Standards + +- Shell scripts must be executable and follow bash best practices +- All scripts should handle errors gracefully +- Use descriptive variable names and add comments for complex logic +- Test scripts on different environments when possible + +### Documentation Standards + +- **ALWAYS update CHANGELOG.md** - Every PR that introduces new functionality, fixes issues, or makes changes must include a detailed changelog entry with issue references (e.g., "Fixes #16") + - Add entries under `## **WORK IN PROGRESS**` section following AlCalzone release-script standard + - Use format: `- (author) **TYPE**: Description of user-visible change (Fixes #XX)` + - Types: **NEW** (features), **FIXED** (bugs), **ENHANCED** (improvements), **TESTING** (test additions), **CI/CD** (automation) + - Focus on user impact, not technical implementation details +- **ALWAYS update README.md** - When adding new functionality, infrastructure, or changing how users interact with the repository, update the relevant sections +- Include detailed CHANGELOG.md entries for user-facing changes with specific details about what was added/changed/fixed + +### Testing Requirements + +When adding new scripts or modifying existing ones, you **MUST**: + +1. **Create/Update Tests**: Add comprehensive test cases in the appropriate `test-.sh` file +2. **Test All Functions**: Cover success scenarios, error conditions, and edge cases +3. **Validate Dependencies**: Ensure tests check for required files and dependencies +4. **Test Integration**: Add integration tests if scripts interact with other components +5. **Run Full Suite**: Execute `./tests/test-runner.sh` to verify all tests pass +6. **Update Documentation**: Modify `TESTING.md` if adding new testing patterns + +#### Test Categories Required: +- **Unit Tests**: Individual function and command-line option testing +- **Integration Tests**: Script interaction and workflow testing +- **Error Handling Tests**: Missing files, invalid parameters, network failures +- **Consistency Tests**: Version synchronization and file state validation + +## Release Process + +### Preparing a Release + +1. **Update Version**: Use the version management script + ```bash + ./scripts/manage-versions.sh update X.Y.Z + ``` + +2. **Update CHANGELOG.md**: Add comprehensive change descriptions + +3. **Verify Consistency**: Run consistency checks + ```bash + ./scripts/manage-versions.sh check + ``` + +4. **Test Everything**: Run the complete test suite + ```bash + ./tests/test-runner.sh + ``` + +5. **Validate Integration**: Test download URLs and integration scripts + +### Post-Release Tasks + +- Announce significant changes to the ioBroker community +- Monitor for user feedback and issues +- Update documentation if needed based on user questions + +## Troubleshooting + +### Common Issues + +**Test Environment Setup Failures**: Ensure all scripts have execute permissions +```bash +chmod +x scripts/*.sh tests/*.sh +``` + +**Version Inconsistencies**: Use the sync command to restore consistency +```bash +./scripts/manage-versions.sh sync +``` + +**Failed Tests**: Run specific test files for detailed debugging +```bash +./tests/test-runner.sh tests/test-specific-feature.sh +``` + +### Debugging Failed Tests + +1. Run specific failing test file for detailed output +2. Check the error message in the test summary +3. Verify script dependencies and file permissions +4. Test the actual script manually with the failing scenario + +### Repository Maintenance + +**Regular Tasks:** +- Monitor test results in CI/CD +- Update dependencies and security patches +- Review and respond to community feedback +- Keep documentation current with template changes + +**Quarterly Tasks:** +- Review version management system performance +- Analyze test coverage and add missing scenarios +- Update examples to reflect current ioBroker best practices +- Evaluate new testing or automation opportunities + +--- + +**For general usage information**, return to the [main README](../README.md) or consult the [setup guide](setup.md) for template integration instructions. \ No newline at end of file diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..2bf35ad --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,221 @@ +# GitHub Copilot Setup Guide + +This guide walks you through setting up GitHub Copilot for ioBroker adapter development, from initial subscription to template integration. + +## ๐Ÿ“‹ Table of Contents + +- [Prerequisites and Basic GitHub Copilot Setup](#prerequisites-and-basic-github-copilot-setup) +- [Template Integration](#template-integration) +- [Validation and Testing](#validation-and-testing) +- [Organization-Specific Setup](#organization-specific-setup) + +## Prerequisites and Basic GitHub Copilot Setup + +Before using this template, ensure you have GitHub Copilot properly set up in your repository. If you're new to GitHub Copilot, follow these steps: + +### Step 1: GitHub Copilot Subscription & Installation + +1. **Subscribe to GitHub Copilot** + - Visit [GitHub Copilot](https://github.com/features/copilot) and subscribe to GitHub Copilot Individual or Business + - Ensure your subscription is active and includes your target repository + +2. **Install GitHub Copilot Extension** + - **VS Code**: Install the [GitHub Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) + - **JetBrains IDEs**: Install GitHub Copilot from the plugin marketplace + - **Vim/Neovim**: Use the [copilot.vim](https://github.com/github/copilot.vim) plugin + - **Other editors**: Check [GitHub Copilot documentation](https://docs.github.com/en/copilot) for your editor + +3. **Authenticate GitHub Copilot** + - Open your editor and sign in to GitHub Copilot when prompted + - Verify authentication by typing code in any file - you should see Copilot suggestions + +### Step 2: Repository Setup & Validation + +1. **Enable Copilot for Your Repository** + ```bash + # Navigate to your ioBroker adapter repository + cd your-iobroker-adapter + + # Ensure you're logged into GitHub CLI (optional but recommended) + gh auth login + ``` + +2. **Create Basic GitHub Copilot Structure** + ```bash + # Create .github directory if it doesn't exist + mkdir -p .github + + # Verify Copilot can access your repository + # Open any .js/.ts file and start typing - you should see suggestions + ``` + +3. **Verify Copilot is Working** + - Open a JavaScript or TypeScript file in your repository + - Start typing a function or comment + - You should see grayed-out suggestions from Copilot + - Press `Tab` to accept suggestions or `Esc` to dismiss + +### Step 3: Test Basic Functionality + +Create a simple test to verify Copilot is working with your repository: + +```javascript +// Create a file test-copilot.js and start typing this comment: +// Function to add two numbers + +// Copilot should suggest a function implementation when you press Enter +``` + +**Expected behavior:** Copilot should suggest code completions as you type. + +### Troubleshooting Basic Setup + +| Problem | Solution | +|---------|----------| +| No suggestions appear | Check authentication and subscription status | +| Repository not accessible | Verify organization settings and permissions | +| Extension not working | Reinstall Copilot extension and restart editor | +| Authentication issues | Sign out and sign back in to GitHub Copilot | + +**โœ… Setup Complete!** Once you have Copilot working and showing suggestions in your repository, you can proceed to integrate the ioBroker template below. + +### Quick Reference Checklist + +For experienced GitHub Copilot users, here's a quick checklist: + +- [ ] GitHub Copilot subscription is active +- [ ] Copilot extension installed in your editor +- [ ] Authentication completed (can see suggestions when typing) +- [ ] Repository permissions configured (for organizations) +- [ ] Basic functionality tested (suggestions appear in .js/.ts files) +- [ ] Ready to integrate ioBroker template + +**New to GitHub Copilot?** Follow the detailed [Prerequisites & Basic Setup](#prerequisites-and-basic-github-copilot-setup) above. + +## Template Integration + +### Quick Start + +> **โš ๏ธ Prerequisites Required:** Before proceeding, ensure you've completed the [Basic GitHub Copilot Setup](#prerequisites-and-basic-github-copilot-setup) above. + +1. **For Existing Copilot Users (Recommended)** + - If you already have a `.github/copilot-instructions.md` file, merge the content from this template rather than replacing it + - Use GitHub Copilot to help you merge the instructions: "Merge my existing copilot instructions with the template from https://github.com/DrozmotiX/ioBroker-Copilot-Instructions maintaining project-specific context" + - Add the template version reference to track updates + +2. **For New Copilot Users** + - Download the latest version of [`template.md`](../template.md) + - Save it as `.github/copilot-instructions.md` in your adapter repository's `.github/` folder + - Customize sections marked with `[CUSTOMIZE]` for your specific adapter requirements + +3. **Verification & Activation** + - Verify GitHub Copilot is working in your repository (should show suggestions when typing) + - The ioBroker-specific instructions will automatically be used by Copilot when working in your codebase + - Test by opening a JavaScript file and typing ioBroker-related code - you should see relevant suggestions + +### Integration Steps + +> **โš ๏ธ Important:** Ensure GitHub Copilot is working in your repository before proceeding. If you need setup help, see the [Prerequisites & Basic Setup](#prerequisites-and-basic-github-copilot-setup) section above. + +**For repositories with existing Copilot instructions:** +```bash +# Navigate to your ioBroker adapter repository +cd your-iobroker-adapter + +# Verify Copilot is working (should show suggestions when you type) +# Open any .js file and type: // Function to connect to ioBroker +# You should see Copilot suggestions appear + +# Ask GitHub Copilot to merge the instructions +# Use the following prompt in your editor: +# "Merge my existing .github/copilot-instructions.md with the ioBroker template +# from https://github.com/DrozmotiX/ioBroker-Copilot-Instructions/blob/main/template.md +# Keep project-specific content and add version: 0.4.0" +# NOTE: Exclude the HTML comment block at the top of the template" +``` + +**For new repositories (first-time Copilot setup):** +```bash +# Navigate to your ioBroker adapter repository +cd your-iobroker-adapter + +# Verify basic Copilot setup is complete +# Open any .js file and start typing - you should see suggestions +# If no suggestions appear, complete the basic setup first + +# Create .github directory if it doesn't exist +mkdir -p .github + +# Download the latest template +curl -o .github/copilot-instructions.md https://raw.githubusercontent.com/DrozmotiX/ioBroker-Copilot-Instructions/main/template.md + +# Remove the template comment block at the top (lines starting with $/d' .github/copilot-instructions.md + +# Commit the changes +git add .github/copilot-instructions.md +git commit -m "Add GitHub Copilot instructions for ioBroker development" +git push +``` + +## Validation and Testing + +After completing the integration, verify everything is working correctly: + +```bash +# Test that Copilot uses the ioBroker instructions +# 1. Open any .js or .ts file in your adapter +# 2. Start typing ioBroker-related code: +# Example: // Create new ioBroker adapter instance +# Example: this.setState( +# Example: // Handle device connection + +# 3. Copilot should now provide ioBroker-specific suggestions +# 4. Check that suggestions follow the patterns from the template +``` + +**Expected Results:** +- Copilot suggestions should be more relevant to ioBroker development +- Error handling should follow ioBroker patterns +- Test suggestions should include `@iobroker/testing` framework usage +- README updates should follow ioBroker documentation standards + +## Organization-Specific Setup + +
+Click to expand organization setup instructions (only relevant if your repository is part of a GitHub organization) + +### Step 4: Repository Permissions (For Organizations) + +If your repository is part of an organization: + +1. **Check Organization Settings** + - Go to your GitHub organization settings + - Navigate to "Copilot" in the left sidebar + - Ensure your repository is included in the allowed repositories + +2. **Verify Team Access** + - Ensure your team has Copilot access enabled + - Check that repository access policies allow Copilot usage + +### Organization-Specific Troubleshooting + +| Problem | Solution | +|---------|----------| +| Organization access denied | Contact organization admin to enable Copilot access | +| Repository not in allowed list | Add repository to organization's Copilot allowed repositories | +| Team access issues | Verify team has Copilot license allocation | +| Policy restrictions | Review organization Copilot policies and permissions | + +### Organization Best Practices + +- **Centralized Configuration**: Consider creating organization-level Copilot instruction templates +- **Access Management**: Use teams to manage Copilot access across repositories +- **Policy Compliance**: Ensure Copilot usage complies with organization security policies +- **Training**: Provide team training on Copilot best practices for ioBroker development + +
+ +--- + +**Next Steps:** Return to the [main README](../README.md) to explore what's included in the template and see examples of how it enhances ioBroker development. \ No newline at end of file diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..89a8cf6 --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,231 @@ +# Testing Documentation for Users + +This document provides testing information relevant to users of the ioBroker Copilot Instructions template. For detailed technical testing infrastructure, see [TESTING.md](../TESTING.md). + +## ๐Ÿ“‹ Table of Contents + +- [Testing Your Template Integration](#testing-your-template-integration) +- [Validating Copilot Instructions](#validating-copilot-instructions) +- [Automated Template Version Checking](#automated-template-version-checking) +- [Testing Best Practices](#testing-best-practices) + +## Testing Your Template Integration + +After integrating the ioBroker Copilot Instructions template into your adapter repository, use these tests to verify everything is working correctly. + +### Basic Functionality Test + +```bash +# Test that Copilot uses the ioBroker instructions +# 1. Open any .js or .ts file in your adapter +# 2. Start typing ioBroker-related code: +# Example: // Create new ioBroker adapter instance +# Example: this.setState( +# Example: // Handle device connection + +# 3. Copilot should now provide ioBroker-specific suggestions +# 4. Check that suggestions follow the patterns from the template +``` + +### Expected Results + +After successful integration, you should observe: + +- **Context-aware suggestions** specific to ioBroker development patterns +- **Error handling** that follows ioBroker best practices +- **Test suggestions** that include `@iobroker/testing` framework usage +- **README updates** that follow ioBroker documentation standards +- **Dependency management** suggestions aligned with ioBroker ecosystem + +### Testing Scenarios + +#### 1. Adapter Instance Creation +```javascript +// Type this comment in a JavaScript file: +// Create new ioBroker adapter instance + +// Expected: Copilot should suggest ioBroker adapter initialization patterns +``` + +#### 2. State Management +```javascript +// Type this code: +this.setState( + +// Expected: Copilot should suggest proper ioBroker state setting patterns +``` + +#### 3. Error Handling +```javascript +// Type this comment: +// Handle connection error + +// Expected: Copilot should suggest ioBroker-appropriate error handling +``` + +#### 4. Testing Framework +```javascript +// Type this comment: +// Write integration test + +// Expected: Copilot should suggest @iobroker/testing framework patterns +``` + +## Validating Copilot Instructions + +### Template Version Verification + +Check that your template includes the correct version information: + +```bash +# Verify your local template version +grep "Version:" .github/copilot-instructions.md | head -1 +``` + +Expected output should show the current version: +``` +**Version:** 0.4.0 +``` + +### Template Source Verification + +Ensure your template references the correct source: + +```bash +# Check template source reference +grep "Template Source:" .github/copilot-instructions.md | head -1 +``` + +Expected output: +``` +**Template Source:** https://github.com/DrozmotiX/ioBroker-Copilot-Instructions +``` + +### Content Validation + +Verify key sections are present in your template: + +```bash +# Check for essential sections +grep -E "## (Testing|README Updates|Dependency Updates|JSON-Config|Error Handling)" .github/copilot-instructions.md +``` + +## Automated Template Version Checking + +### Quick Version Check + +Use the provided script to check if your template is up-to-date: + +```bash +# 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 +- Provide update guidance if your template is outdated +- Show you what's changed in newer versions + +### Setting Up Automated Checking + +Add this GitHub Action to automatically monitor your template version: + +```yaml +# .github/workflows/check-copilot-template.yml +name: Check Copilot Template Version +on: + schedule: + - cron: '0 0 * * 0' # Weekly check + workflow_dispatch: + +jobs: + check-template: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Check template version + run: | + CURRENT_VERSION=$(grep "Version:" .github/copilot-instructions.md | head -1 | sed 's/.*Version:\s*//') + LATEST_VERSION=$(curl -s https://raw.githubusercontent.com/DrozmotiX/ioBroker-Copilot-Instructions/main/template.md | grep "Version:" | head -1 | sed 's/.*Version:\s*//') + if [ "$CURRENT_VERSION" != "$LATEST_VERSION" ]; then + echo "Template is outdated. Current: $CURRENT_VERSION, Latest: $LATEST_VERSION" + exit 1 + fi +``` + +## Testing Best Practices + +### Regular Testing Schedule + +- **Weekly**: Test basic Copilot functionality with ioBroker patterns +- **Monthly**: Check for template updates and validate suggestions quality +- **Before releases**: Ensure Copilot suggestions align with your adapter's specific patterns + +### Documentation Testing + +When updating your adapter documentation, verify that Copilot suggestions: + +1. **Follow ioBroker standards**: Suggestions should match community conventions +2. **Include required sections**: Installation, Configuration, Usage, Changelog, License, Support +3. **Use proper formatting**: README entries should follow the `## **WORK IN PROGRESS**` pattern +4. **Reference issues**: Changelog entries should include issue references (fixes #XX) + +### Code Quality Testing + +Regularly verify that Copilot suggestions: + +- Use `@iobroker/adapter-core` for base functionality +- Prefer built-in Node.js modules when possible +- Include proper error handling for ioBroker contexts +- Follow established ioBroker adapter patterns + +### Integration Testing + +Test Copilot suggestions for: + +- **CI/CD integration**: GitHub Actions workflows for ioBroker adapters +- **Testing frameworks**: `@iobroker/testing` usage patterns +- **Dependency management**: npm best practices for ioBroker ecosystem +- **Security practices**: Credential handling and API testing patterns + +### Performance Testing + +Monitor Copilot performance with your template: + +- **Response time**: Suggestions should appear promptly +- **Relevance**: Suggestions should be contextually appropriate +- **Accuracy**: Code suggestions should be syntactically correct +- **Consistency**: Similar contexts should produce similar suggestions + +### Troubleshooting Common Issues + +#### Copilot Not Using Template Instructions + +**Symptoms**: Suggestions don't reflect ioBroker patterns +**Solutions**: +1. Verify `.github/copilot-instructions.md` exists and is properly formatted +2. Check that the template version is current +3. Restart your editor to reload Copilot instructions +4. Ensure the file is committed to your repository + +#### Generic Suggestions Instead of ioBroker-Specific + +**Symptoms**: Suggestions are too generic or don't match ioBroker conventions +**Solutions**: +1. Check template integration completeness +2. Verify customization sections marked with `[CUSTOMIZE]` are properly configured +3. Ensure your code context clearly indicates ioBroker development +4. Test with more specific ioBroker-related comments and code + +#### Outdated Suggestions + +**Symptoms**: Suggestions reference old patterns or deprecated methods +**Solutions**: +1. Update to the latest template version +2. Review changelog for breaking changes or new best practices +3. Clear Copilot cache if available in your editor +4. Verify your local template matches the latest repository version + +--- + +**For setup instructions**, see the [setup guide](setup.md). **For technical testing details**, consult [TESTING.md](../TESTING.md). **Return to the [main README](../README.md)** for overview and navigation. \ No newline at end of file From 1ccfef3d9d227a4bd9a7e509c13a5086258ac677 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Sep 2025 22:14:34 +0000 Subject: [PATCH 03/10] Promote Copilot-assisted template merging and add community support reference Co-authored-by: DutchmanNL <7318445+DutchmanNL@users.noreply.github.com> --- README.md | 8 ++++---- docs/maintenance.md | 7 ++++++- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 776da65..4851c29 100644 --- a/README.md +++ b/README.md @@ -22,10 +22,10 @@ This repository provides comprehensive guidance and best practices for leveragin **For experienced Copilot users:** -1. **Download the template**: Get the latest [`template.md`](template.md) -2. **Integrate**: Save as `.github/copilot-instructions.md` in your adapter repository -3. **Customize**: Modify sections marked with `[CUSTOMIZE]` -4. **Verify**: Test that Copilot provides ioBroker-specific suggestions +1. **Use Copilot for Smart Integration**: Instead of simply copying the template, use GitHub Copilot to intelligently merge it with your existing setup +2. **Prompt Copilot**: "Merge the ioBroker template from https://github.com/DrozmotiX/ioBroker-Copilot-Instructions/blob/main/template.md with my existing .github/copilot-instructions.md, maintaining project-specific context and adding version tracking" +3. **Customize**: Review and modify sections marked with `[CUSTOMIZE]` for your specific adapter +4. **Verify**: Test that Copilot provides enhanced ioBroker-specific suggestions **Current Version:** v0.4.0 | **Template:** [`template.md`](template.md) | **Last Updated:** September 2025 diff --git a/docs/maintenance.md b/docs/maintenance.md index 56e0926..b964bd6 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -222,4 +222,9 @@ chmod +x scripts/*.sh tests/*.sh --- -**For general usage information**, return to the [main README](../README.md) or consult the [setup guide](setup.md) for template integration instructions. \ No newline at end of file +**For general usage information**, return to the [main README](../README.md) or consult the [setup guide](setup.md) for template integration instructions. + +## ๐Ÿ’ฌ Community Support + +Join our community discussion about AI-powered ioBroker development: +- **[ioBroker Community Forum - AI meets ioBroker](https://forum.iobroker.net/topic/82238/ki-trifft-iobroker-ein-gemeinsames-abenteuer/4)** - Share experiences, ask questions, and collaborate on improving AI-assisted adapter development \ No newline at end of file From b28a47d79862b36e158b25a59c731670219affe2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Sep 2025 22:20:30 +0000 Subject: [PATCH 04/10] Move community support to top and promote AI development benefits Co-authored-by: DutchmanNL <7318445+DutchmanNL@users.noreply.github.com> --- docs/maintenance.md | 34 ++++++++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/docs/maintenance.md b/docs/maintenance.md index b964bd6..435c037 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -2,8 +2,35 @@ This guide is specifically for maintainers of the ioBroker Copilot Instructions repository. It covers version management, testing infrastructure, and repository maintenance procedures. +## ๐Ÿ’ฌ Community Support & AI-Powered Development + +**Join the AI Revolution in ioBroker Development!** + +Using GitHub Copilot with ioBroker adapter development isn't just about writing code faster โ€“ it's about transforming how we build and maintain adapters. Our community is actively exploring and sharing the benefits: + +### ๐Ÿš€ Why AI-Assisted Development is Game-Changing: +- **Accelerated Development**: Write adapter code 3-5x faster with intelligent suggestions +- **Best Practice Enforcement**: Copilot learns from our template patterns and suggests ioBroker-compliant code +- **Reduced Learning Curve**: New developers can immediately write quality adapter code +- **Consistent Code Quality**: AI helps maintain uniform patterns across the entire ecosystem +- **Error Prevention**: Smart suggestions help avoid common pitfalls and bugs + +### ๐ŸŽฏ Easy Setup, Immediate Benefits: +Setting up GitHub Copilot for ioBroker development takes just minutes, but the productivity gains last forever. The template handles all the complexity โ€“ just integrate it once and let AI supercharge your adapter development. + +### ๐Ÿค Join Our Growing Community: +- **[ioBroker Community Forum - AI meets ioBroker](https://forum.iobroker.net/topic/82238/ki-trifft-iobroker-ein-gemeinsames-abenteuer/4)** - Share experiences, success stories, and collaborate on improving AI-assisted adapter development +- Exchange tips, tricks, and real-world examples +- Get help with setup and advanced configurations +- Contribute to making AI development even better for everyone + +**Ready to experience the future of ioBroker development?** The setup is simple, the benefits are immediate, and the community is here to support you! + +--- + ## ๐Ÿ“‹ Table of Contents +- [Community Support & AI-Powered Development](#-community-support--ai-powered-development) - [Version Management](#version-management) - [Automated Testing Infrastructure](#automated-testing-infrastructure) - [Development Guidelines](#development-guidelines) @@ -222,9 +249,4 @@ chmod +x scripts/*.sh tests/*.sh --- -**For general usage information**, return to the [main README](../README.md) or consult the [setup guide](setup.md) for template integration instructions. - -## ๐Ÿ’ฌ Community Support - -Join our community discussion about AI-powered ioBroker development: -- **[ioBroker Community Forum - AI meets ioBroker](https://forum.iobroker.net/topic/82238/ki-trifft-iobroker-ein-gemeinsames-abenteuer/4)** - Share experiences, ask questions, and collaborate on improving AI-assisted adapter development \ No newline at end of file +**For general usage information**, return to the [main README](../README.md) or consult the [setup guide](setup.md) for template integration instructions. \ No newline at end of file From 424d8d23740b3cc4cb36efa34aa68ac513e35c12 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Sep 2025 22:26:00 +0000 Subject: [PATCH 05/10] Refocus community section on ioBroker and update CHANGELOG Co-authored-by: DutchmanNL <7318445+DutchmanNL@users.noreply.github.com> --- CHANGELOG.md | 5 +++++ docs/maintenance.md | 37 +++++++++++++++++++------------------ 2 files changed, 24 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 97d2a1b..2d9bde3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## **WORK IN PROGRESS** +- (copilot) **ENHANCED**: Reorganized README into focused documentation files by instruction type for better user experience (Fixes #22) +- (copilot) **NEW**: Created separate docs/ directory with setup.md, maintenance.md, and testing.md for clear audience targeting +- (copilot) **ENHANCED**: Promoted intelligent Copilot-assisted template merging instead of 1:1 copying for better version control +- (copilot) **NEW**: Added comprehensive community support section with forum and GitHub contribution guidelines +- (copilot) **ENHANCED**: Made organization-specific setup instructions collapsible to reduce clutter for individual users - (copilot) **ENHANCED**: Standardized changelog format inconsistencies to align with AlCalzone release-script standard - fixed mixed WORK IN PROGRESS formatting and added comprehensive changelog management documentation (Fixes #20) ## [0.4.0] - 2025-09-XX - Automated Version handling & validation by GitHub actions diff --git a/docs/maintenance.md b/docs/maintenance.md index 435c037..5650ec7 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -2,35 +2,36 @@ This guide is specifically for maintainers of the ioBroker Copilot Instructions repository. It covers version management, testing infrastructure, and repository maintenance procedures. -## ๐Ÿ’ฌ Community Support & AI-Powered Development +## ๐Ÿ’ฌ Community Support & Development -**Join the AI Revolution in ioBroker Development!** +**Join the ioBroker Copilot Instructions Community!** -Using GitHub Copilot with ioBroker adapter development isn't just about writing code faster โ€“ it's about transforming how we build and maintain adapters. Our community is actively exploring and sharing the benefits: +This repository serves the ioBroker community by providing standardized GitHub Copilot instructions for adapter development. We're continuously improving these templates based on real-world usage and community feedback. -### ๐Ÿš€ Why AI-Assisted Development is Game-Changing: -- **Accelerated Development**: Write adapter code 3-5x faster with intelligent suggestions -- **Best Practice Enforcement**: Copilot learns from our template patterns and suggests ioBroker-compliant code -- **Reduced Learning Curve**: New developers can immediately write quality adapter code -- **Consistent Code Quality**: AI helps maintain uniform patterns across the entire ecosystem -- **Error Prevention**: Smart suggestions help avoid common pitfalls and bugs +### ๐Ÿ  Why Join Our Community: +- **Share Experiences**: Learn from other developers using Copilot for ioBroker adapter development +- **Collaborate on Improvements**: Help refine templates and best practices +- **Get Support**: Quick help with setup and troubleshooting +- **Accelerated Development**: Write adapter code faster with intelligent suggestions +- **Best Practice Enforcement**: Ensure your adapters follow ioBroker conventions -### ๐ŸŽฏ Easy Setup, Immediate Benefits: -Setting up GitHub Copilot for ioBroker development takes just minutes, but the productivity gains last forever. The template handles all the complexity โ€“ just integrate it once and let AI supercharge your adapter development. +### ๐Ÿค How to Contribute & Participate: +- **[ioBroker Community Forum](https://forum.iobroker.net/topic/82238/ki-trifft-iobroker-ein-gemeinsames-abenteuer/4)** - Join discussions about improving adapter development with AI assistance +- **[Submit Issues](https://github.com/DrozmotiX/ioBroker-Copilot-Instructions/issues)** - Report bugs, suggest improvements, or request new features +- **[GitHub Discussions](https://github.com/DrozmotiX/ioBroker-Copilot-Instructions/discussions)** - Share ideas, ask questions, and collaborate on best practices +- **Share Success Stories**: Help others by sharing what works well in your adapter projects +- **Contribute Templates**: Suggest improvements to existing instructions or propose new patterns -### ๐Ÿค Join Our Growing Community: -- **[ioBroker Community Forum - AI meets ioBroker](https://forum.iobroker.net/topic/82238/ki-trifft-iobroker-ein-gemeinsames-abenteuer/4)** - Share experiences, success stories, and collaborate on improving AI-assisted adapter development -- Exchange tips, tricks, and real-world examples -- Get help with setup and advanced configurations -- Contribute to making AI development even better for everyone +### ๐ŸŽฏ Easy Setup, Lasting Benefits: +Setting up GitHub Copilot with our ioBroker templates takes just minutes. The templates handle the complexity while you focus on building great adapters. -**Ready to experience the future of ioBroker development?** The setup is simple, the benefits are immediate, and the community is here to support you! +**Ready to improve your ioBroker development experience?** The setup is straightforward, the community is supportive, and your contributions help everyone! --- ## ๐Ÿ“‹ Table of Contents -- [Community Support & AI-Powered Development](#-community-support--ai-powered-development) +- [Community Support & Development](#-community-support--development) - [Version Management](#version-management) - [Automated Testing Infrastructure](#automated-testing-infrastructure) - [Development Guidelines](#development-guidelines) From 94ec43b4bddf62f3e36d509f3c77b4053195b157 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Sep 2025 22:29:59 +0000 Subject: [PATCH 06/10] Add community section to README and refocus top section on ioBroker Co-authored-by: DutchmanNL <7318445+DutchmanNL@users.noreply.github.com> --- README.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4851c29..b421729 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,22 @@ This repository provides comprehensive guidance and best practices for leveraging GitHub Copilot in ioBroker adapter development. By using these standardized instructions, developers can: -- **Accelerate development** with AI-powered code suggestions tailored for ioBroker -- **Maintain consistency** across different adapter projects -- **Follow established patterns** and avoid common pitfalls -- **Improve code quality** through proven best practices +- **Accelerate development** with intelligent code suggestions tailored for ioBroker patterns +- **Maintain consistency** across different adapter projects within the ioBroker ecosystem +- **Follow established patterns** and avoid common pitfalls in adapter development +- **Improve code quality** through proven ioBroker best practices - **Reduce learning curve** for new ioBroker adapter developers +## ๐Ÿค Join Our Community + +**Help us improve ioBroker adapter development together!** + +- **[ioBroker Community Forum](https://forum.iobroker.net/topic/82238/ki-trifft-iobroker-ein-gemeinsames-abenteuer/4)** - Share experiences and collaborate on improving adapter development +- **[Submit Issues](https://github.com/DrozmotiX/ioBroker-Copilot-Instructions/issues)** - Report bugs, suggest improvements, or request new features +- **[GitHub Discussions](https://github.com/DrozmotiX/ioBroker-Copilot-Instructions/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](https://www.iobroker.net/) 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. From fe6316b45e24c92e91b8e71c502bb4e76a0ee03e Mon Sep 17 00:00:00 2001 From: Rafal Drozda Date: Fri, 19 Sep 2025 00:51:43 +0200 Subject: [PATCH 07/10] Update docs/maintenance.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/maintenance.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/maintenance.md b/docs/maintenance.md index 5650ec7..a403745 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -154,13 +154,9 @@ For detailed testing documentation, see [TESTING.md](../TESTING.md). ### Documentation Standards -- **ALWAYS update CHANGELOG.md** - Every PR that introduces new functionality, fixes issues, or makes changes must include a detailed changelog entry with issue references (e.g., "Fixes #16") - - Add entries under `## **WORK IN PROGRESS**` section following AlCalzone release-script standard - - Use format: `- (author) **TYPE**: Description of user-visible change (Fixes #XX)` - - Types: **NEW** (features), **FIXED** (bugs), **ENHANCED** (improvements), **TESTING** (test additions), **CI/CD** (automation) - - Focus on user impact, not technical implementation details -- **ALWAYS update README.md** - When adding new functionality, infrastructure, or changing how users interact with the repository, update the relevant sections -- Include detailed CHANGELOG.md entries for user-facing changes with specific details about what was added/changed/fixed +For documentation formatting standards and changelog entry requirements, please refer to: +- [AlCalzone release-script documentation](https://github.com/AlCalzone/release-script/blob/main/README.md) +- [Main README](../README.md) ### Testing Requirements From 59ee90209212bd1b9d372c34358f644dc365f9a3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Sep 2025 22:51:48 +0000 Subject: [PATCH 08/10] Fix forum URLs and restructure setup guide for repository-first approach Co-authored-by: DutchmanNL <7318445+DutchmanNL@users.noreply.github.com> --- README.md | 2 +- docs/maintenance.md | 2 +- docs/setup.md | 255 +++++++++++++++++++++++--------------------- 3 files changed, 134 insertions(+), 125 deletions(-) diff --git a/README.md b/README.md index b421729..2d704fa 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ This repository provides comprehensive guidance and best practices for leveragin **Help us improve ioBroker adapter development together!** -- **[ioBroker Community Forum](https://forum.iobroker.net/topic/82238/ki-trifft-iobroker-ein-gemeinsames-abenteuer/4)** - Share experiences and collaborate on improving adapter development +- **[ioBroker Community Forum](https://forum.iobroker.net/topic/82238/ki-trifft-iobroker-ein-gemeinsames-abenteuer)** - Share experiences and collaborate on improving adapter development - **[Submit Issues](https://github.com/DrozmotiX/ioBroker-Copilot-Instructions/issues)** - Report bugs, suggest improvements, or request new features - **[GitHub Discussions](https://github.com/DrozmotiX/ioBroker-Copilot-Instructions/discussions)** - Share ideas, ask questions, and collaborate on best practices diff --git a/docs/maintenance.md b/docs/maintenance.md index a403745..4a3b002 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -16,7 +16,7 @@ This repository serves the ioBroker community by providing standardized GitHub C - **Best Practice Enforcement**: Ensure your adapters follow ioBroker conventions ### ๐Ÿค How to Contribute & Participate: -- **[ioBroker Community Forum](https://forum.iobroker.net/topic/82238/ki-trifft-iobroker-ein-gemeinsames-abenteuer/4)** - Join discussions about improving adapter development with AI assistance +- **[ioBroker Community Forum](https://forum.iobroker.net/topic/82238/ki-trifft-iobroker-ein-gemeinsames-abenteuer)** - Join discussions about improving adapter development with AI assistance - **[Submit Issues](https://github.com/DrozmotiX/ioBroker-Copilot-Instructions/issues)** - Report bugs, suggest improvements, or request new features - **[GitHub Discussions](https://github.com/DrozmotiX/ioBroker-Copilot-Instructions/discussions)** - Share ideas, ask questions, and collaborate on best practices - **Share Success Stories**: Help others by sharing what works well in your adapter projects diff --git a/docs/setup.md b/docs/setup.md index 2bf35ad..c6a35e0 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,184 +1,193 @@ # GitHub Copilot Setup Guide -This guide walks you through setting up GitHub Copilot for ioBroker adapter development, from initial subscription to template integration. +This guide walks you through setting up GitHub Copilot for ioBroker adapter development, focusing on repository-level Copilot integration and automated template merging. ## ๐Ÿ“‹ Table of Contents -- [Prerequisites and Basic GitHub Copilot Setup](#prerequisites-and-basic-github-copilot-setup) +- [Repository Copilot Setup (Essential)](#repository-copilot-setup-essential) - [Template Integration](#template-integration) +- [Advanced: IDE Setup](#advanced-ide-setup) - [Validation and Testing](#validation-and-testing) - [Organization-Specific Setup](#organization-specific-setup) -## Prerequisites and Basic GitHub Copilot Setup +## Repository Copilot Setup (Essential) -Before using this template, ensure you have GitHub Copilot properly set up in your repository. If you're new to GitHub Copilot, follow these steps: +**For existing ioBroker adapter repositories** - This section covers setting up GitHub Copilot at the repository level, which is essential for all users. -### Step 1: GitHub Copilot Subscription & Installation +### Step 1: GitHub Copilot Subscription 1. **Subscribe to GitHub Copilot** - Visit [GitHub Copilot](https://github.com/features/copilot) and subscribe to GitHub Copilot Individual or Business - Ensure your subscription is active and includes your target repository -2. **Install GitHub Copilot Extension** - - **VS Code**: Install the [GitHub Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) - - **JetBrains IDEs**: Install GitHub Copilot from the plugin marketplace - - **Vim/Neovim**: Use the [copilot.vim](https://github.com/github/copilot.vim) plugin - - **Other editors**: Check [GitHub Copilot documentation](https://docs.github.com/en/copilot) for your editor - -3. **Authenticate GitHub Copilot** - - Open your editor and sign in to GitHub Copilot when prompted - - Verify authentication by typing code in any file - you should see Copilot suggestions +### Step 2: Repository Copilot Instructions Setup -### Step 2: Repository Setup & Validation - -1. **Enable Copilot for Your Repository** +1. **Navigate to your existing ioBroker adapter repository** ```bash - # Navigate to your ioBroker adapter repository - cd your-iobroker-adapter - - # Ensure you're logged into GitHub CLI (optional but recommended) - gh auth login + cd your-existing-iobroker-adapter ``` -2. **Create Basic GitHub Copilot Structure** +2. **Ensure you have GitHub Copilot instructions file** ```bash # Create .github directory if it doesn't exist mkdir -p .github - # Verify Copilot can access your repository - # Open any .js/.ts file and start typing - you should see suggestions + # Check if you already have Copilot instructions + ls -la .github/copilot-instructions.md ``` -3. **Verify Copilot is Working** - - Open a JavaScript or TypeScript file in your repository - - Start typing a function or comment - - You should see grayed-out suggestions from Copilot - - Press `Tab` to accept suggestions or `Esc` to dismiss +3. **If you don't have a copilot-instructions.md file, let Copilot create one** + - Open any code file in your repository in your preferred editor + - Start typing: `// This is an ioBroker adapter for` + - GitHub Copilot will automatically create basic instructions when you commit changes to `.github/copilot-instructions.md` -### Step 3: Test Basic Functionality +4. **If your existing config seems corrupt, start fresh** + ```bash + # Remove existing file if needed + rm .github/copilot-instructions.md + + # Let Copilot create a new one by starting development work + ``` -Create a simple test to verify Copilot is working with your repository: +## Template Integration -```javascript -// Create a file test-copilot.js and start typing this comment: -// Function to add two numbers +**Automated template merging** - Always combine with existing instructions, never replace entirely. -// Copilot should suggest a function implementation when you press Enter -``` +### Step 1: Prepare for Template Integration -**Expected behavior:** Copilot should suggest code completions as you type. +1. **Ensure version tracking in your repository** + Your `.github/copilot-instructions.md` should include: + ```markdown + **Version:** [current-version] + **Template Source:** https://github.com/DrozmotiX/ioBroker-Copilot-Instructions + **Custom Sections:** [Preserve during updates] + ``` -### Troubleshooting Basic Setup +2. **Identify your custom sections** + - Mark any project-specific instructions with `[CUSTOMIZE]` tags + - These will be preserved during template updates -| Problem | Solution | -|---------|----------| -| No suggestions appear | Check authentication and subscription status | -| Repository not accessible | Verify organization settings and permissions | -| Extension not working | Reinstall Copilot extension and restart editor | -| Authentication issues | Sign out and sign back in to GitHub Copilot | +### Step 2: Automated Template Merging -**โœ… Setup Complete!** Once you have Copilot working and showing suggestions in your repository, you can proceed to integrate the ioBroker template below. +**Use GitHub Copilot to intelligently merge templates** - This preserves your custom content and maintains version control. -### Quick Reference Checklist +1. **Prompt GitHub Copilot for smart merging** + In your editor, use this prompt: + ``` + "Merge the ioBroker template from https://github.com/DrozmotiX/ioBroker-Copilot-Instructions/blob/main/template.md + with my existing .github/copilot-instructions.md. Preserve all [CUSTOMIZE] sections and project-specific + context while adding the latest ioBroker best practices. Update the version to 0.4.0." + ``` -For experienced GitHub Copilot users, here's a quick checklist: +2. **Verify version tracking** + Ensure your updated file includes: + - Current template version (0.4.0) + - Template source reference + - Your custom sections intact + - Project-specific context preserved -- [ ] GitHub Copilot subscription is active -- [ ] Copilot extension installed in your editor -- [ ] Authentication completed (can see suggestions when typing) -- [ ] Repository permissions configured (for organizations) -- [ ] Basic functionality tested (suggestions appear in .js/.ts files) -- [ ] Ready to integrate ioBroker template +3. **Commit with version control** + ```bash + git add .github/copilot-instructions.md + git commit -m "Update Copilot instructions to template v0.4.0, preserve custom sections" + ``` -**New to GitHub Copilot?** Follow the detailed [Prerequisites & Basic Setup](#prerequisites-and-basic-github-copilot-setup) above. +### Step 3: Custom Section Management -## Template Integration +**Keep customizations safe** - Always use the custom section approach: -### Quick Start +1. **Structure your custom content** + ```markdown + ## [CUSTOMIZE] Project-Specific Instructions + + ### My Adapter Specific Patterns + - Custom patterns for your adapter + - Project-specific error handling + - Unique API integrations + + **Note:** This section is preserved during template updates + ``` -> **โš ๏ธ Prerequisites Required:** Before proceeding, ensure you've completed the [Basic GitHub Copilot Setup](#prerequisites-and-basic-github-copilot-setup) above. +2. **Version validation** + Use the version check script to ensure you're up-to-date: + ```bash + curl -s https://raw.githubusercontent.com/DrozmotiX/ioBroker-Copilot-Instructions/main/scripts/check-template-version.sh | bash + ``` -1. **For Existing Copilot Users (Recommended)** - - If you already have a `.github/copilot-instructions.md` file, merge the content from this template rather than replacing it - - Use GitHub Copilot to help you merge the instructions: "Merge my existing copilot instructions with the template from https://github.com/DrozmotiX/ioBroker-Copilot-Instructions maintaining project-specific context" - - Add the template version reference to track updates +## Advanced: IDE Setup -2. **For New Copilot Users** - - Download the latest version of [`template.md`](../template.md) - - Save it as `.github/copilot-instructions.md` in your adapter repository's `.github/` folder - - Customize sections marked with `[CUSTOMIZE]` for your specific adapter requirements +**Optional IDE integration** - For developers who want to use Copilot directly in their development environment. -3. **Verification & Activation** - - Verify GitHub Copilot is working in your repository (should show suggestions when typing) - - The ioBroker-specific instructions will automatically be used by Copilot when working in your codebase - - Test by opening a JavaScript file and typing ioBroker-related code - you should see relevant suggestions +### IDE Installation & Configuration -### Integration Steps +1. **Install GitHub Copilot Extension** + - **VS Code**: Install the [GitHub Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) + - **JetBrains IDEs**: Install GitHub Copilot from the plugin marketplace + - **Vim/Neovim**: Use the [copilot.vim](https://github.com/github/copilot.vim) plugin + - **Other editors**: Check [GitHub Copilot documentation](https://docs.github.com/en/copilot) for your editor -> **โš ๏ธ Important:** Ensure GitHub Copilot is working in your repository before proceeding. If you need setup help, see the [Prerequisites & Basic Setup](#prerequisites-and-basic-github-copilot-setup) section above. +2. **Authenticate GitHub Copilot in IDE** + - Open your editor and sign in to GitHub Copilot when prompted + - Verify authentication by typing code in any file - you should see Copilot suggestions -**For repositories with existing Copilot instructions:** -```bash -# Navigate to your ioBroker adapter repository -cd your-iobroker-adapter - -# Verify Copilot is working (should show suggestions when you type) -# Open any .js file and type: // Function to connect to ioBroker -# You should see Copilot suggestions appear - -# Ask GitHub Copilot to merge the instructions -# Use the following prompt in your editor: -# "Merge my existing .github/copilot-instructions.md with the ioBroker template -# from https://github.com/DrozmotiX/ioBroker-Copilot-Instructions/blob/main/template.md -# Keep project-specific content and add version: 0.4.0" -# NOTE: Exclude the HTML comment block at the top of the template" -``` +3. **Test IDE Integration** + ```javascript + // Create a file test-copilot.js and start typing this comment: + // Function to add two numbers + + // Copilot should suggest a function implementation when you press Enter + ``` -**For new repositories (first-time Copilot setup):** -```bash -# Navigate to your ioBroker adapter repository -cd your-iobroker-adapter +### IDE Troubleshooting -# Verify basic Copilot setup is complete -# Open any .js file and start typing - you should see suggestions -# If no suggestions appear, complete the basic setup first +| Problem | Solution | +|---------|----------| +| No suggestions appear | Check authentication and subscription status | +| Extension not working | Reinstall Copilot extension and restart editor | +| Authentication issues | Sign out and sign back in to GitHub Copilot | -# Create .github directory if it doesn't exist -mkdir -p .github +## Validation and Testing + +After completing the template integration, verify everything is working correctly: -# Download the latest template -curl -o .github/copilot-instructions.md https://raw.githubusercontent.com/DrozmotiX/ioBroker-Copilot-Instructions/main/template.md +### Repository-Level Testing -# Remove the template comment block at the top (lines starting with $/d' .github/copilot-instructions.md +```bash +# Test that Copilot instructions are properly integrated +# 1. Check your .github/copilot-instructions.md file exists +ls -la .github/copilot-instructions.md -# Commit the changes -git add .github/copilot-instructions.md -git commit -m "Add GitHub Copilot instructions for ioBroker development" -git push +# 2. Verify version information is present +grep "Version:" .github/copilot-instructions.md +grep "Template Source:" .github/copilot-instructions.md + +# 3. Check for custom sections +grep "\[CUSTOMIZE\]" .github/copilot-instructions.md ``` -## Validation and Testing +### Development Testing -After completing the integration, verify everything is working correctly: +Test that Copilot provides ioBroker-specific suggestions: -```bash -# Test that Copilot uses the ioBroker instructions -# 1. Open any .js or .ts file in your adapter -# 2. Start typing ioBroker-related code: -# Example: // Create new ioBroker adapter instance -# Example: this.setState( -# Example: // Handle device connection - -# 3. Copilot should now provide ioBroker-specific suggestions -# 4. Check that suggestions follow the patterns from the template -``` +1. **Open any .js or .ts file in your adapter** +2. **Start typing ioBroker-related code:** + - Example: `// Create new ioBroker adapter instance` + - Example: `this.setState(` + - Example: `// Handle device connection` + +3. **Verify enhanced suggestions:** + - Copilot should provide ioBroker-specific patterns + - Error handling should follow ioBroker best practices + - Test suggestions should include `@iobroker/testing` framework usage + +### Expected Results -**Expected Results:** -- Copilot suggestions should be more relevant to ioBroker development -- Error handling should follow ioBroker patterns -- Test suggestions should include `@iobroker/testing` framework usage -- README updates should follow ioBroker documentation standards +After successful integration, you should observe: +- **Context-aware suggestions** specific to ioBroker development patterns +- **Error handling** that follows ioBroker best practices +- **Test suggestions** that include `@iobroker/testing` framework usage +- **README updates** that follow ioBroker documentation standards +- **Dependency management** suggestions aligned with ioBroker ecosystem ## Organization-Specific Setup From 99df44a4d4eb18d0e0fbf10a85b5a3a58a93ba53 Mon Sep 17 00:00:00 2001 From: Rafal Drozda Date: Fri, 19 Sep 2025 00:52:25 +0200 Subject: [PATCH 09/10] Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2d704fa..b8fd5e2 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Your contributions help make adapter development better for the entire ioBroker 3. **Customize**: Review and modify sections marked with `[CUSTOMIZE]` for your specific adapter 4. **Verify**: Test that Copilot provides enhanced ioBroker-specific suggestions -**Current Version:** v0.4.0 | **Template:** [`template.md`](template.md) | **Last Updated:** September 2025 +![Version](https://img.shields.io/github/package-json/v/DrozmotiX/ioBroker-Copilot-Instructions?label=Current%20Version) | **Template:** [`template.md`](template.md) | ![Last Updated](https://img.shields.io/github/last-commit/DrozmotiX/ioBroker-Copilot-Instructions?label=Last%20Updated) ## ๐Ÿ“š Documentation From 42a01432dac97317daeabf5ca9bc4948ffac1b03 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Sep 2025 23:02:23 +0000 Subject: [PATCH 10/10] Rewrite repository introduction to focus on community and ioBroker rather than AI Co-authored-by: DutchmanNL <7318445+DutchmanNL@users.noreply.github.com> --- README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index b8fd5e2..6593ec3 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,16 @@ > A comprehensive template and best practices library for using GitHub Copilot in ioBroker adapter development -## ๐ŸŽฏ Goal of this Repository +## ๐ŸŽฏ About This Repository -This repository provides comprehensive guidance and best practices for leveraging GitHub Copilot in ioBroker adapter development. By using these standardized instructions, developers can: +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. -- **Accelerate development** with intelligent code suggestions tailored for ioBroker patterns -- **Maintain consistency** across different adapter projects within the ioBroker ecosystem -- **Follow established patterns** and avoid common pitfalls in adapter development -- **Improve code quality** through proven ioBroker best practices -- **Reduce learning curve** for new ioBroker adapter developers +**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