Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 25 additions & 4 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,25 +21,46 @@ You are working on the ioBroker Copilot Instructions template repository. This r
- `README.md` - Repository documentation explaining how to use the template
- `CHANGELOG.md` - Version history and detailed change documentation
- `TESTING.md` - Automated testing infrastructure documentation
- `config/metadata.json` - **CENTRALIZED VERSION REGISTRY** - Contains all component versions and deployment configuration
- `scripts/check-template-version.sh` - Version checking utility for users
- `scripts/manage-versions.sh` - Master version management script (show/check/sync/update commands)
- `scripts/manage-versions.sh` - **Enhanced version management** (show/check/sync/update/update-component/list-components commands)
- `scripts/extract-version.sh` - Dynamic version extraction from template and current dates
- `scripts/update-versions.sh` - Automated documentation synchronization script
- `scripts/shared-utils.sh` - **Enhanced with component version functions** for metadata access
- `tests/test-runner.sh` - Main test execution framework for all scripts
- `tests/test-*.sh` - Comprehensive test suites for each script and integration scenarios
- `tests/test-version-separation.sh` - **NEW** - Tests for multi-component versioning system
- `.github/workflows/test-scripts.yml` - GitHub Actions workflow for continuous testing
- `.github/workflows/deploy-on-version-change.yml` - **NEW** - Automated deployment on main version changes
- `.github/copilot-instructions.md` - THIS file - repository-specific instructions

## Template Development Guidelines

### Version Management
- Use the dynamic version management system (`scripts/manage-versions.sh`) for all version updates
- Update versions with: `./scripts/manage-versions.sh update X.Y.Z` (automatically updates all files)
- **Enhanced Multi-Component Versioning**: Repository now supports independent versioning for templates, GitHub Actions, and other components
- **Main Package Version**: Always tied to template version and triggers automated deployment when changed
- **Component Updates**: Use `./scripts/manage-versions.sh update-component <component_path> <version>` for individual component versions
- **Version Policy Enforcement**: All version changes must be incremental (higher than previous version)
- **Centralized Configuration**: All version information stored in `config/metadata.json` with full component tracking
- **Main Version Updates**: Use `./scripts/manage-versions.sh update X.Y.Z` (automatically updates template and package versions together)
- **Version Validation**: Built-in checks ensure main version matches template version and prevents downgrades
- **Automated Deployment**: Changes to main version trigger deployment workflow automatically
- Document all changes in `CHANGELOG.md` with detailed descriptions
- Use semantic versioning (MAJOR.MINOR.PATCH)
- Use semantic versioning (MAJOR.MINOR.PATCH) for all components
- Validate consistency with: `./scripts/manage-versions.sh check`
- Sync documentation with: `./scripts/manage-versions.sh sync` when needed

### GitHub Copilot Review Instructions for Version Changes
When reviewing PRs that modify versions:
1. **Always verify main version changes match template version** - these must be identical
2. **Check that version increments are higher than previous** - prevent downgrades
3. **Validate component version changes** - ensure they follow semantic versioning
4. **Confirm CHANGELOG.md is updated** - require detailed change documentation
5. **Check for deployment readiness** - main version changes trigger automated deployment
6. **Review version policy compliance** - ensure all changes follow increment requirements
7. **Validate metadata consistency** - run `./scripts/manage-versions.sh check` mentally
8. **Component separation compliance** - ensure components use independent versioning appropriately

### Template Content Standards
- Focus on practical, actionable guidance for ioBroker adapter developers
- Include comprehensive examples with real code snippets
Expand Down
206 changes: 206 additions & 0 deletions .github/workflows/deploy-on-version-change.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,206 @@
name: Deploy on Version Change

on:
push:
branches: [ main ]
paths:
- 'config/metadata.json'
- 'template.md'
- 'package.json'
workflow_dispatch:
inputs:
force_deploy:
description: 'Force deployment regardless of version change'
required: false
default: 'false'
type: boolean

jobs:
detect-version-change:
runs-on: ubuntu-latest
outputs:
version_changed: ${{ steps.check-version.outputs.changed }}
old_version: ${{ steps.check-version.outputs.old_version }}
new_version: ${{ steps.check-version.outputs.new_version }}
deploy_needed: ${{ steps.check-version.outputs.deploy_needed }}

steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 2 # Need previous commit to compare

- name: Check for version changes
id: check-version
run: |
echo "🔍 Checking for main version changes..."

# Get current version from metadata
CURRENT_VERSION=$(jq -r '.version' config/metadata.json)
echo "Current version: $CURRENT_VERSION"

# Get previous version from git (if available)
if git show HEAD~1:config/metadata.json >/dev/null 2>&1; then
PREVIOUS_VERSION=$(git show HEAD~1:config/metadata.json | jq -r '.version' 2>/dev/null || echo "unknown")
echo "Previous version: $PREVIOUS_VERSION"
else
PREVIOUS_VERSION="unknown"
echo "Previous version: unknown (no previous commit)"
fi

# Set outputs
echo "old_version=$PREVIOUS_VERSION" >> $GITHUB_OUTPUT
echo "new_version=$CURRENT_VERSION" >> $GITHUB_OUTPUT

# Check if deployment is needed
DEPLOY_NEEDED="false"

if [[ "${{ github.event.inputs.force_deploy }}" == "true" ]]; then
echo "🚀 Force deployment requested"
DEPLOY_NEEDED="true"
elif [[ "$PREVIOUS_VERSION" != "$CURRENT_VERSION" ]]; then
echo "🔄 Version changed from $PREVIOUS_VERSION to $CURRENT_VERSION"
DEPLOY_NEEDED="true"
else
echo "⏸️ No version change detected"
fi

echo "deploy_needed=$DEPLOY_NEEDED" >> $GITHUB_OUTPUT
echo "changed=$DEPLOY_NEEDED" >> $GITHUB_OUTPUT

if [[ "$DEPLOY_NEEDED" == "true" ]]; then
echo "✅ Deployment will proceed"
else
echo "⏭️ Skipping deployment"
fi

validate-version-policy:
needs: detect-version-change
if: needs.detect-version-change.outputs.deploy_needed == 'true'
runs-on: ubuntu-latest

steps:
- name: Checkout repository
uses: actions/checkout@v4

- name: Validate version increment policy
run: |
echo "🔍 Validating version increment policy..."

OLD_VERSION="${{ needs.detect-version-change.outputs.old_version }}"
NEW_VERSION="${{ needs.detect-version-change.outputs.new_version }}"

# Make script executable
chmod +x scripts/manage-versions.sh

# Validate increment policy
if ./scripts/manage-versions.sh validate-increment "main" "$OLD_VERSION" "$NEW_VERSION"; then
echo "✅ Version increment validation passed"
else
echo "❌ Version increment validation failed"
exit 1
fi

- name: Validate metadata consistency
run: |
echo "🔍 Validating metadata and file consistency..."

# Run consistency check
if ./scripts/manage-versions.sh check; then
echo "✅ Version consistency validation passed"
else
echo "❌ Version consistency validation failed"
echo ""
echo "💡 Run './scripts/manage-versions.sh sync' to fix inconsistencies"
exit 1
fi

deploy-package:
needs: [detect-version-change, validate-version-policy]
if: needs.detect-version-change.outputs.deploy_needed == 'true'
runs-on: ubuntu-latest

steps:
- name: Checkout repository
uses: actions/checkout@v4

- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '18'

- name: Run test suite
run: |
echo "🧪 Running complete test suite before deployment..."
chmod +x tests/test-runner.sh scripts/*.sh

if ./tests/test-runner.sh; then
echo "✅ All tests passed"
else
echo "❌ Tests failed - deployment aborted"
exit 1
fi

- name: Create release tag
run: |
NEW_VERSION="${{ needs.detect-version-change.outputs.new_version }}"
echo "🏷️ Creating release tag v$NEW_VERSION"

git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"

# Create annotated tag with version info
git tag -a "v$NEW_VERSION" -m "Release version $NEW_VERSION

Package version: $NEW_VERSION
Template version: $NEW_VERSION

Automated deployment triggered by version change in config/metadata.json
Previous version: ${{ needs.detect-version-change.outputs.old_version }}

See CHANGELOG.md for detailed changes."

git push origin "v$NEW_VERSION"

- name: Generate deployment summary
run: |
echo "# 🚀 Deployment Summary" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "| Item | Value |" >> $GITHUB_STEP_SUMMARY
echo "|------|-------|" >> $GITHUB_STEP_SUMMARY
echo "| Previous Version | ${{ needs.detect-version-change.outputs.old_version }} |" >> $GITHUB_STEP_SUMMARY
echo "| New Version | ${{ needs.detect-version-change.outputs.new_version }} |" >> $GITHUB_STEP_SUMMARY
echo "| Trigger | ${{ github.event_name }} |" >> $GITHUB_STEP_SUMMARY
echo "| Git Tag | v${{ needs.detect-version-change.outputs.new_version }} |" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "## ✅ Validation Status" >> $GITHUB_STEP_SUMMARY
echo "- Version increment policy: ✅ Passed" >> $GITHUB_STEP_SUMMARY
echo "- Metadata consistency: ✅ Passed" >> $GITHUB_STEP_SUMMARY
echo "- Test suite: ✅ Passed" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "## 📦 Components" >> $GITHUB_STEP_SUMMARY
echo "Main template and package versions have been updated to ${{ needs.detect-version-change.outputs.new_version }}" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "Individual component versions remain independent and can be updated separately using:" >> $GITHUB_STEP_SUMMARY
echo '`./scripts/manage-versions.sh update-component <component> <version>`' >> $GITHUB_STEP_SUMMARY

notify-completion:
needs: [detect-version-change, deploy-package]
if: always() && needs.detect-version-change.outputs.deploy_needed == 'true'
runs-on: ubuntu-latest

steps:
- name: Deployment success notification
if: needs.deploy-package.result == 'success'
run: |
echo "🎉 Deployment completed successfully!"
echo "New version: ${{ needs.detect-version-change.outputs.new_version }}"
echo "Git tag: v${{ needs.detect-version-change.outputs.new_version }}"

- name: Deployment failure notification
if: needs.deploy-package.result == 'failure'
run: |
echo "❌ Deployment failed!"
echo "Version: ${{ needs.detect-version-change.outputs.new_version }}"
echo "Please check the workflow logs and fix any issues."
exit 1
54 changes: 53 additions & 1 deletion config/metadata.json
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
{
"version": "0.4.0",
"warning": "⚠️ CHANGING THE MAIN VERSION ABOVE WILL TRIGGER AUTOMATED PACKAGE UPDATE DEPLOYMENT",
"repository": {
"url": "https://github.com/DrozmotiX/ioBroker-Copilot-Instructions",
"raw_base": "https://raw.githubusercontent.com/DrozmotiX/ioBroker-Copilot-Instructions/main"
},
"template": {
"file": "template.md",
"target_path": ".github/copilot-instructions.md"
"target_path": ".github/copilot-instructions.md",
"version": "0.4.0"
},
"scripts": {
"check_template_version": "scripts/check-template-version.sh",
Expand All @@ -19,5 +21,55 @@
"template-update",
"automation"
]
},
"components": {
"github_actions": {
"weekly_version_check": {
"file": "templates/weekly-version-check-action.yml",
"version": "0.2.1",
"description": "GitHub Action for automated template version monitoring"
},
"github_action_snippet": {
"file": "snippets/github-action-version-check.yml",
"version": "0.2.0",
"description": "Reusable GitHub Action snippet for template checking"
}
},
"templates": {
"initial_setup_automation": {
"file": "templates/initial-setup-automation.md",
"version": "0.3.0",
"description": "Automated setup template with GitHub Copilot integration"
},
"copy_paste_template": {
"file": "templates/copy-paste-template.md",
"version": "0.2.0",
"description": "Quick template update guide for GitHub Copilot"
},
"automated_template_update": {
"file": "templates/automated-template-update.md",
"version": "0.2.0",
"description": "Automated template update instructions"
}
},
"snippets": {
"version_check_command": {
"file": "snippets/version-check-command.md",
"version": "0.1.1",
"description": "Reusable version check command snippet"
},
"version_management_commands": {
"file": "snippets/version-management-commands.md",
"version": "0.1.0",
"description": "Version management script usage examples"
}
}
},
"version_policy": {
"main_version_source": "template.version",
"main_version_description": "Main package version must always match template version",
"component_versioning": "independent",
"increment_policy": "must_be_higher_than_previous",
"deployment_trigger": "main_version_change"
}
}
Loading