Palantir Upgrade & Migration

Overview

Safely upgrade foundry-platform-sdk versions, handle breaking changes, and migrate between Foundry API versions. Includes a step-by-step upgrade checklist and rollback procedure.

Prerequisites

• Current foundry-platform-sdk installed
• Git for version control
• Test suite covering Foundry API calls
• Staging environment

Instructions

Step 1: Check Current Version and Available Updates

set -euo pipefail
pip show foundry-platform-sdk | grep -E "^(Name|Version)"
pip index versions foundry-platform-sdk 2>/dev/null | head -3
# Check OSDK version too
npm list @osdk/client 2>/dev/null || echo "OSDK not installed"

Step 2: Review Changelog

# Check GitHub releases for breaking changes
python -c "
import urllib.request, json
url = 'https://api.github.com/repos/palantir/foundry-platform-python/releases?per_page=5'
releases = json.loads(urllib.request.urlopen(url).read())
for r in releases:
    print(f'{r[\"tag_name\"]:12s} {r[\"published_at\"][:10]}')
    body = r.get('body', '')[:200]
    if 'BREAKING' in body.upper():
        print(f'  *** BREAKING CHANGES DETECTED ***')
    print()
"

Step 3: Create Upgrade Branch and Update

set -euo pipefail
git checkout -b upgrade/foundry-sdk-$(date +%Y%m%d)
pip install --upgrade foundry-platform-sdk
pip show foundry-platform-sdk | grep Version

Step 4: Run Tests and Fix Breaking Changes

set -euo pipefail
pytest tests/ -v --tb=short 2>&1 | tee upgrade-test-results.txt
# Review failures for breaking changes
grep -E "FAILED|ERROR" upgrade-test-results.txt

Common breaking changes between versions:

# v0.x → v1.x: Client initialization changed
# Before:
client = foundry.FoundryClient(auth=foundry.UserTokenAuth(token="..."))
# After:
client = foundry.FoundryClient(
    auth=foundry.UserTokenAuth(hostname="...", token="..."),
    hostname="...",
)

# v1.x → v2.x: Ontology methods moved
# Before:
client.ontology.list_objects(...)
# After:
client.ontologies.OntologyObject.list(...)

Step 5: Verify in Staging

# Deploy to staging and run smoke tests
FOUNDRY_HOSTNAME=$STAGING_HOSTNAME pytest tests/integration/ -v

Step 6: Rollback Procedure

# Pin previous version
pip install foundry-platform-sdk==0.8.0
# Or revert the branch
git checkout main -- requirements.txt
pip install -r requirements.txt

Output

• Updated SDK version with all tests passing
• Breaking changes identified and fixed
• Staging verification completed
• Rollback procedure documented

Error Handling

Resources

• foundry-platform-python Releases
• PyPI Package
• API Changelog

Next Steps

For CI integration during upgrades, see palantir-ci-integration.