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.

💬 Community Support & Development

Join the ioBroker Copilot Instructions Community!

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

🤝 How to Contribute & Participate:

ioBroker Community Forum - Join discussions about improving adapter development with AI assistance
Submit Issues - Report bugs, suggest improvements, or request new features
GitHub 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

🎯 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 improve your ioBroker development experience? The setup is straightforward, the community is supportive, and your contributions help everyone!

Version Management

This repository includes comprehensive version management scripts that automatically handle version consistency across all documentation.

Available Commands

# 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:

# 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:

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

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

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

For documentation formatting standards and changelog entry requirements, please refer to:

Testing Requirements

When adding new scripts or modifying existing ones, you MUST:

Create/Update Tests: Add comprehensive test cases in the appropriate test-<script-name>.sh file
Test All Functions: Cover success scenarios, error conditions, and edge cases
Validate Dependencies: Ensure tests check for required files and dependencies
Test Integration: Add integration tests if scripts interact with other components
Run Full Suite: Execute ./tests/test-runner.sh to verify all tests pass
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

Update Version: Use the version management script
```
./scripts/manage-versions.sh update X.Y.Z
```
Update CHANGELOG.md: Add comprehensive change descriptions
Verify Consistency: Run consistency checks
```
./scripts/manage-versions.sh check
```
Test Everything: Run the complete test suite
```
./tests/test-runner.sh
```
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

chmod +x scripts/*.sh tests/*.sh

Version Inconsistencies: Use the sync command to restore consistency

./scripts/manage-versions.sh sync

Failed Tests: Run specific test files for detailed debugging

./tests/test-runner.sh tests/test-specific-feature.sh

Debugging Failed Tests

Run specific failing test file for detailed output
Check the error message in the test summary
Verify script dependencies and file permissions
Test the actual script manually with the failing scenario