Migration Guide

This guide helps you migrate between different versions of BFCI Components.

Version 1.0.0 Migration

Breaking Changes

1. Component Registry Structure

   • Old: registry.gitlab.bluefly.io / components / <name >- New:registry.gitlab.bluefly.io / Blueflyio / internal - projects / llm / bfcicomponents / <name >2. Configuration Format

# Old format

 include:
   - component: test
     version: 1.0.0

# New format

 include:
   - component: [COMPONENT_REGISTRY] / [email protected]
 ```text

3. Cache Configuration

 ```yaml

# Old format

 cache:
   paths: ["node_modules"]

# New format

 cache:
   key: [CI_COMMIT_REF_SLUG]
   paths:
     - node_modules/
     - .npm/
 ```text

### Migration Steps
1. Update Registry References

 ```yaml
 variables:
   COMPONENT_REGISTRY: registry.gitlab.bluefly.io / Blueflyio / internal - projects / llm / bfcicomponents
 ```text

2. Update Component Includes

 ```yaml
 include:
   - component: [COMPONENT_REGISTRY] / [email protected]
   - component: [COMPONENT_REGISTRY] / [email protected]
 ```text

3. Update Cache Configuration

 ```yaml
 cache:
   key: [CI_COMMIT_REF_SLUG]
   paths:
     - node_modules/
     - .npm/
     - vendor/
     - .composer/
 ```text

4. Update Job Definitions

 ```yaml
 test:
   extends: .test
   variables:
     TEST_COMMAND: 'npm test'
 ```text

## Compatibility Matrix
| Component | v0.x | v1.0.0 | Notes                             |
| --------- | ---- | ------ | --------------------------------- |
| test      | ✓    | ✓      | Breaking changes in configuration |
| lint      | ✓    | ✓      | New options available             |
| build     | ✓    | ✓      | Cache configuration changes       |
| deploy    | ✗    | ✓      | New in v1.0.0                     |

## Common Issues

### Registry Access
1. Update GitLab CI / CD variables
2. Check authentication tokens
3. Verify registry permissions

### Configuration Errors
1. Check component versions
2. Verify syntax format
3. Update cache paths

### Pipeline Failures
1. Review job logs
2. Check dependencies
3. Verify environment setup

## Best Practices
1. Version Pinning

 - Use exact versions
 - Avoid latest tag
 - Document versions

2. Gradual Migration

 - Test in staging
 - Migrate one component at a time
 - Keep backups

3. Testing Strategy

 - Run test pipelines
 - Verify functionality
 - Check performance

## Rollback Procedure
If issues occur:

1. Revert to previous version
2. Document issues
3. Contact support

## Support Resources
- [Component Registry Guide](. / component - registry.md)
- [Configuration Guide](. / configuration.md)
- [Support Guide](. / support.md)

Need help? [Create an issue](https://gitlab.bluefly.io / Blueflyio / internal - projects / llm / bfcicomponents/ - /issues)