Skip to content

UPDATE_GUIDE.md

Latest commit

 

History

History
219 lines (164 loc) · 4.94 KB

UPDATE_GUIDE.md

File metadata and controls

219 lines (164 loc) · 4.94 KB

ADK Update Guide

Quick Update

To pull the latest changes and ensure everything works:

./update.sh

That's it! The script will:

  1. ✅ Check for uncommitted changes
  2. ✅ Pull latest from GitHub
  3. ✅ Update dependencies
  4. ✅ Run compatibility checks
  5. ✅ Run tests to ensure nothing broke

Update Script Options

Basic Usage

# Standard update (recommended)
./update.sh

# Skip tests (faster, but less safe)
./update.sh --skip-tests

# Force update even with uncommitted changes
./update.sh --force

# Show help
./update.sh --help

Compatibility with Manual Git Pull

The script is designed to work seamlessly even if you've already run git pull:

git pull origin main
./update.sh

If you've already pulled changes, the script will:

  1. Detect that the repository is up-to-date
  2. Continue to check/update dependencies
  3. Continue to run compatibility checks and tests

This ensures your environment is always correct, regardless of how you got the code updates.

What the Script Does

1. Safety Checks

  • Verifies you're in the git repository
  • Checks for uncommitted changes
  • Offers to stash changes if needed

2. Pull Updates

  • Fetches latest from GitHub
  • Shows what will be updated
  • Pulls changes safely

3. Dependency Management

  • Detects if requirements.txt changed
  • Auto-updates dependencies (if in virtual environment)
  • Verifies critical dependencies are installed

4. Compatibility Checks

  • Verifies Python 3.11+ is installed
  • Checks all critical dependencies:
    • atlassian-python-api (Confluence)
    • beautifulsoup4 (GCP docs reader)
    • python-dotenv (Environment config)

5. Testing

  • Runs all backend service tests
  • Ensures new changes don't break existing functionality
  • Can be skipped with --skip-tests if needed

6. Summary

  • Shows what was updated
  • Displays recent commits
  • Provides commands to review changes

Example Workflows

Daily Update (Recommended)

# Pull latest changes and verify everything works
./update.sh

Quick Update (Skip Tests)

# Faster, but less thorough
./update.sh --skip-tests

Update with Uncommitted Work

# Script will offer to stash your changes
./update.sh

# Or force through (not recommended)
./update.sh --force

Troubleshooting

"You have uncommitted changes"

Solution: Either commit your changes or let the script stash them:

# Option 1: Commit your changes
git add .
git commit -m "Your changes"
./update.sh

# Option 2: Let script stash them
./update.sh
# (script will prompt to stash)

# Option 3: Force update (risky)
./update.sh --force

"Missing dependencies detected"

Solution: The script will auto-install if you're in a virtual environment. Otherwise:

pip install -r requirements.txt

"Tests failed"

Solution: Review the test output and fix issues before proceeding:

# Run tests manually to see details
pytest backend/services/test_*.py -v

# Or skip tests temporarily (not recommended for production)
./update.sh --skip-tests

"Not in a virtual environment"

Solution: Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate
./update.sh

Manual Update (Alternative)

If you prefer to update manually:

# 1. Pull changes
git pull origin main

# 2. Update dependencies
pip install -r requirements.txt --upgrade

# 3. Run tests
pytest backend/services/test_*.py -v

# 4. Check what changed
git log --stat HEAD@{1}..HEAD

Best Practices

✅ Do This

  • Run ./update.sh regularly (daily or weekly)
  • Review the summary of changes after update
  • Keep your virtual environment activated
  • Commit your work before updating

❌ Avoid This

  • Using --force without understanding the risks
  • Skipping tests in production environments
  • Updating without reviewing what changed
  • Running updates without a virtual environment

CI/CD Integration

For automated deployments, use the script in your CI/CD pipeline:

# Example GitHub Actions workflow
- name: Update and Test
  run: |
    ./update.sh --skip-tests  # Tests run separately in CI

Version Compatibility

The update script ensures compatibility with:

  • Python: 3.11+
  • Dependencies: Automatically updated from requirements.txt
  • Services: All backend services tested after update

Getting Help

If you encounter issues:

  1. Check the error message - The script provides detailed error messages
  2. Review recent changes: git log --stat HEAD@{1}..HEAD
  3. Run tests manually: pytest backend/services/test_*.py -v
  4. Check dependencies: pip list | grep -E "(atlassian|beautifulsoup4|dotenv)"

Related Documentation

Created: 2025-11-18
Last Updated: 2025-11-18
Maintainer: Security Agent Team