Skip to content

UPGRADING.md

Latest commit

 

History

History
369 lines (262 loc) · 11.4 KB

UPGRADING.md

File metadata and controls

369 lines (262 loc) · 11.4 KB
Raw

Upgrading Guide

This guide will help you upgrade Code Review Guardian to newer versions.

General Upgrade Process

  1. Update the package:

    composer update nowo-tech/code-review-guardian

  2. Review the CHANGELOG: Check CHANGELOG.md for breaking changes and new features.

  3. Update your configuration (if needed): The code-review-guardian.yaml configuration file is automatically updated during installation. If you have custom modifications, you may need to review and update them.

  4. Update the script (if needed): The code-review-guardian.sh script is automatically updated during installation. If you have custom modifications, you may need to reapply them.

Version-Specific Upgrade Notes

Upgrading to 1.1.0

This release changes how the root wrapper script is refreshed on composer install / composer update, and expands CI/tooling. No configuration file format changes.

Behavior change: wrapper script updates are opt-in

Previously, code-review-guardian.sh in the project root was overwritten on every install/update.

From 1.1.0:

  • Missing wrapper → installed as before
  • Same content as the package → left unchanged
  • Local wrapper differs → not overwritten; Composer shows a warning with MD5s

To restore automatic overwrite of the wrapper, add to your project's composer.json:

{
  "extra": {
    "code-review-guardian": {
      "auto_update_wrapper": true
    }
  }
}

Then run composer update nowo-tech/code-review-guardian (or delete the local script and reinstall to get a fresh copy).

What You Need to Do

  1. Update the package: 
    composer update nowo-tech/code-review-guardian
  2. If you rely on the package always refreshing the root script, enable auto_update_wrapper as above.
  3. Otherwise, no action required — custom local wrappers are preserved by default.

Other notes

  • Package still supports PHP >=8.1 <8.6. CI focuses on PHP 8.2–8.5 with Symfony 7.4 / 8.0 / 8.1.
  • YAML config, GGA docs install rules, and uninstall behavior are unchanged (except wrapper overwrite policy above).

Upgrading to 1.0.1

This is a patch release that improves development experience and test stability. No breaking changes.

Improvements

  • Development Tools: Makefile commands now work without requiring a running container. All commands use docker-compose run --rm for consistency.
  • Code Coverage: Xdebug is now properly configured in the Dockerfile, enabling code coverage reports out of the box.
  • Test Stability: Improved PHPUnit test assertions for better reliability.

What You Need to Do

No action required - This is a maintenance release with no breaking changes. Simply update the package:

composer update nowo-tech/code-review-guardian

Benefits

  • Better development experience: Makefile commands work without starting containers
  • Code coverage available by default in Docker environment
  • More reliable test suite

Upgrading to 1.0.0

First Stable Release

Version 1.0.0 is the first stable release of Code Review Guardian. This version represents a mature, production-ready codebase with:

What's New:

  • Stable release: First production-ready version
  • Complete modular architecture: Refactored script structure for improved maintainability
  • Comprehensive documentation: All documentation in English
  • Full test coverage: 38 tests with 100% code coverage
  • Composer plugin: Automatic installation and updates

What You Need to Do:

  1. Update the package:

    composer update nowo-tech/code-review-guardian

  2. No breaking changes: This version is fully backward compatible with v0.0.7

    • All functionality remains the same
    • Configuration files remain compatible
    • Script behavior unchanged

  3. Verify the upgrade:

    # Check version
composer show nowo-tech/code-review-guardian

# Test the script
./code-review-guardian.sh --help

Benefits:

  • Production-ready stability
  • Improved code organization and maintainability
  • Comprehensive documentation
  • Full test coverage ensures reliability

Migration from v0.0.7:

  • No migration steps required
  • Direct upgrade from v0.0.7 to v1.0.0
  • All existing configurations and scripts remain compatible

Upgrading to 0.0.7

Script Architecture Changes

Version 0.0.7 introduces a major architectural change to the script structure:

What Changed:

  • The code-review-guardian.sh script in your project root is now minimal (~40 lines)
  • The script now acts as a lightweight wrapper that delegates to the actual implementation in vendor/
  • All logic is executed from vendor/nowo-tech/code-review-guardian/bin/main.sh
  • The script automatically detects the vendor directory location

What You Need to Do:

  1. No action required - The script will be automatically updated on composer update
  2. The script will automatically detect and use the vendor directory
  3. All functionality remains the same - this is a transparent change

Benefits:

  • Script in project root is minimal and always up-to-date
  • Code is maintained in vendor, not copied to your project
  • Easier to maintain and update
  • Better separation of concerns

Troubleshooting: If you encounter issues after upgrading:

  • Ensure the package is properly installed: composer install
  • Verify vendor directory exists: ls vendor/nowo-tech/code-review-guardian/bin/main.sh
  • The script will show an error message if the vendor package is not found

Upgrading to 0.0.5

New Features

  • Complete configuration implementation: All YAML configuration options are now fully parsed, validated, and applied
  • Enhanced configuration validation: Automatic validation of configuration values (types, ranges, valid options)
  • Improved script output: All configuration values are now displayed when running the script

Changes

  • AGENTS_CONFIG.md included in package: The file is now included in the Composer package and available in vendor/
  • Documentation URLs updated: All GitHub repository URLs now use the correct repository name

Migration Steps

  1. Update the package:

    composer update nowo-tech/code-review-guardian

  2. No configuration changes required: Your existing code-review-guardian.yaml file remains compatible

  3. Verify the upgrade:

    # Run the script to see all configuration options being loaded
./code-review-guardian.sh

  4. Check configuration validation:

    • The script will now validate all configuration values
    • Invalid values will show warnings
    • Review any warnings and update your configuration if needed

What's New

  • All configuration options are now fully implemented and validated
  • Script output shows all active configuration settings
  • Better error messages for invalid configuration values
  • docs/AGENTS_CONFIG.md is now available in the installed package

Upgrading to 0.0.3

Breaking Changes

  • Configuration file renamed: .code-review-guardian.yml → code-review-guardian.yaml
    • Removed leading dot for better visibility
    • Changed extension from .yml to .yaml (standard YAML extension)
    • Files now appear together alphabetically: code-review-guardian.sh and code-review-guardian.yaml

Migration Steps

  1. Update the package:

    composer update nowo-tech/code-review-guardian

  2. Rename your configuration file (if you have an existing .code-review-guardian.yml):

    # Rename the old config file to the new name
mv .code-review-guardian.yml code-review-guardian.yaml

    Note: If you don't have a custom configuration, the new file will be automatically created during installation.

  3. Update your .gitignore (if needed):

    • The package automatically updates .gitignore to include code-review-guardian.yaml
    • You can manually remove the old entry .code-review-guardian.yml if present

  4. Verify the upgrade:

    # Check that both files exist
ls -la code-review-guardian.*
# Should show: code-review-guardian.sh and code-review-guardian.yaml

# Test that the script works
./code-review-guardian.sh

What Changed

  • Configuration file: .code-review-guardian.yml → code-review-guardian.yaml

    • Same format and content, only filename changed
    • Both files now appear together when listing files alphabetically

  • Script behavior: The script (code-review-guardian.sh) now automatically updates on every composer install and composer update

    • Ensures you always have the latest version with bug fixes and new features

Rollback

If you need to rollback to version 0.0.2:

composer require --dev nowo-tech/code-review-guardian:^0.0.2
mv code-review-guardian.yaml .code-review-guardian.yml

Upgrading to 0.0.1+

This is the initial release. If you're installing for the first time, follow the installation instructions in the README.

New Features

  • Provider-agnostic code review guardian
  • Automatic framework detection
  • Framework-specific configuration files
  • Git Guardian Angel (GGA) for automated code reviews
  • AI Agents support (OpenAI, Anthropic, GitHub Copilot)
  • Token configuration via .env file

Breaking Changes

  • None (initial release)

Migration Steps

  1. Install the package:

    composer require --dev nowo-tech/code-review-guardian

  2. The package will automatically:

    • Detect your framework
    • Install the appropriate configuration file (code-review-guardian.yaml)
    • Install the code review script (code-review-guardian.sh)
    • Update your .gitignore file

  3. Run the code review guardian:

    ./code-review-guardian.sh

  4. Customize the configuration file if needed:

    # Edit code-review-guardian.yaml to customize checks and thresholds
nano code-review-guardian.yaml

Troubleshooting

Script not found after upgrade

If the script is missing after upgrading:

composer install

This will reinstall the script files.

Permission errors

If you get permission errors:

chmod +x code-review-guardian.sh

Configuration file not found

If the configuration file is missing:

  1. Check if the framework was detected correctly:

    # The plugin should show: "Detected framework: SYMFONY" (or LARAVEL, etc.)
composer install

  2. If the framework was not detected, the generic configuration will be used.

  3. You can manually create a configuration file:

    # Copy from the package
cp vendor/nowo-tech/code-review-guardian/config/generic/code-review-guardian.yaml code-review-guardian.yaml

Conflicts with custom modifications

If you've modified the script or configuration and it conflicts with the new version:

  1. Backup your custom files:

    cp code-review-guardian.sh code-review-guardian.sh.backup
cp code-review-guardian.yaml code-review-guardian.yaml.backup

  2. Reinstall the package:

    composer reinstall nowo-tech/code-review-guardian

  3. Reapply your custom modifications if needed

Getting Help

If you encounter issues during upgrade:

  1. Check the CHANGELOG for known issues
  2. Review the README for usage examples
  3. Open an issue on GitHub with:
    • Your current version
    • Target version
    • Framework (Symfony, Laravel, etc.)
    • Git provider (GitHub, GitLab, Bitbucket, etc.)
    • Error messages
    • Steps to reproduce