SDK Publishing Guide¶

For SwisperStudio Team
Last Updated: 2025-11-08
Current SDK Version: 0.5.0

📦 Overview¶

The SwisperStudio SDK is published to GitHub Packages (private) as swisper-studio-sdk.

Publishing is automated via GitHub Actions - just create a git tag and push!

Note: This is a private package accessible only within the Fintama GitHub organization.

🚀 How to Publish a New SDK Version¶

Prerequisites¶

GitHub repository access - Push to main branch and create tags
GitHub Packages permissions - Automatic via GITHUB_TOKEN
Version number decided - Follow semantic versioning
Fintama organization membership - Required for private package access

Step 1: Update Version Number (2 mins)¶

Edit sdk/pyproject.toml:

[project]
name = "swisper-studio-sdk"
version = "0.6.0"  # ← UPDATE THIS
description = "SwisperStudio SDK - Tracing integration for Swisper"

Action: - [ ] Change version number - [ ] Follow semantic versioning (MAJOR.MINOR.PATCH)

Step 2: Update CHANGELOG (5 mins)¶

Edit sdk/CHANGELOG.md:

## [0.6.0] - 2025-11-XX

### Added
- New feature X
- New feature Y

### Fixed
- Bug fix Z

### Changed
- Breaking change A (if MAJOR version bump)

Action: - [ ] Add new version section at top - [ ] List all changes (Added/Fixed/Changed/Removed) - [ ] Use present tense (e.g., "Add feature" not "Added feature")

Step 3: Update README (optional) (3 mins)¶

If there are new features, update sdk/README.md: - Installation instructions (if changed) - New features in "Features" section - New examples in "Quick Start"

Action: - [ ] Update README if needed - [ ] Keep examples accurate

Step 4: Commit Changes (2 mins)¶

cd /root/projects/swisper_studio

git add sdk/pyproject.toml sdk/CHANGELOG.md sdk/README.md
git commit -m "chore: bump SDK version to 0.6.0"
git push origin main

Action: - [ ] Commit version bump - [ ] Push to main branch - [ ] Wait for main branch CI to pass (if any)

Step 5: Create Git Tag (1 min)¶

# Create annotated tag
git tag -a sdk-v0.6.0 -m "SDK v0.6.0 - Brief description of changes"

# Push tag to trigger publish workflow
git push origin sdk-v0.6.0

⚠️ Important: Tag format MUST be sdk-v{VERSION} (e.g., sdk-v0.6.0)

Action: - [ ] Create tag with sdk-v prefix - [ ] Push tag to origin - [ ] GitHub Actions will trigger automatically

Step 6: Monitor Workflow (5 mins)¶

Go to GitHub Actions: - https://github.com/Fintama/swisper_studio/actions

Look for: "Publish SDK to GitHub Packages" workflow

Expected steps: 1. ✅ Checkout code 2. ✅ Set up Python 3. ✅ Build package 4. ✅ Verify version 5. ✅ Check package 6. ✅ Publish to GitHub Packages 7. ✅ Create GitHub Release

Action: - [ ] Monitor workflow progress - [ ] Check for errors (red ❌) - [ ] Verify all steps pass (green ✅)

Step 7: Verify Publication (5 mins)¶

Check GitHub Packages¶

URL: https://github.com/Fintama/swisper_studio/packages

Verify: - [ ] Package swisper-studio-sdk appears - [ ] New version listed - [ ] Version number correct - [ ] Package marked as private

Check GitHub Release¶

URL: https://github.com/Fintama/swisper_studio/releases

Verify: - [ ] Release created with tag sdk-v0.6.0 - [ ] Release notes present - [ ] Marked "For Fintama Internal Use Only" - [ ] Installation instructions include GitHub Packages auth

Test Installation¶

# Create test environment
python -m venv /tmp/sdk-test
source /tmp/sdk-test/bin/activate

# Install new version
pip install swisper-studio-sdk==0.6.0

# Test import
python -c "from swisper_studio_sdk import create_traced_graph; print('✅ SDK v0.6.0 works!')"

# Cleanup
deactivate
rm -rf /tmp/sdk-test

Action: - [ ] Test installation - [ ] Verify imports work - [ ] Check version: pip show swisper-studio-sdk

Step 8: Notify Stakeholders (5 mins)¶

Update Documentation: - [ ] Update SWISPER_TEAM_HANDOVER_SDK_UPGRADE.md if needed - [ ] Update main implementation plan if major version

Notify: - [ ] Swisper team (if they need to upgrade) - [ ] Document in team chat/Slack - [ ] Add to release notes/sprint summary

📊 Semantic Versioning¶

Follow SemVer strictly:

MAJOR version (1.0.0 → 2.0.0)¶

When: Breaking changes that require code updates

Examples: - Changed function signatures - Removed public APIs - Changed behavior significantly

Action: Update major version, document migration guide

MINOR version (0.5.0 → 0.6.0)¶

When: New features, backward compatible

Examples: - Added new functions/classes - Added optional parameters - Enhanced existing features

Action: Update minor version, document new features

PATCH version (0.5.0 → 0.5.1)¶

When: Bug fixes, no new features

Examples: - Fixed crashes - Fixed incorrect behavior - Performance improvements - Documentation fixes

Action: Update patch version, document fixes

🔧 One-Time Setup¶

GitHub Packages Authentication¶

Good news: No additional setup needed! 🎉

GitHub Actions uses the built-in GITHUB_TOKEN secret which has: - ✅ Automatic access to GitHub Packages - ✅ No manual token creation required - ✅ Scoped to repository automatically

What's already configured: - Workflow has packages: write permission - Uses ${{ secrets.GITHUB_TOKEN }} for publishing - Private package within Fintama organization

Action: - [ ] Verify you have write access to repository - [ ] Verify GitHub Actions is enabled - [x] ~~Create API tokens~~ (not needed!)

That's it! GitHub handles authentication automatically.

⚠️ Troubleshooting¶

Error: "Version already exists"¶

Cause: Can't re-publish same version

Solution: 1. Increment version in pyproject.toml 2. Create new tag 3. Note: You can delete package versions in GitHub Packages if needed (Settings → Packages)

Error: "Invalid credentials" or "403 Forbidden"¶

Cause: Insufficient permissions

Solution: 1. Verify workflow has packages: write permission 2. Check GITHUB_TOKEN is used (automatic) 3. Verify you're a member of Fintama organization 4. Check repository settings allow GitHub Packages

Error: "Version mismatch"¶

Cause: Git tag version doesn't match pyproject.toml version

Solution: 1. Check tag: sdk-v0.6.0 should match version = "0.6.0" 2. Delete wrong tag: git tag -d sdk-v0.6.0 && git push origin :refs/tags/sdk-v0.6.0 3. Fix version in pyproject.toml 4. Create correct tag

Workflow doesn't trigger¶

Cause: Tag doesn't match pattern sdk-v*

Solution: 1. Tag MUST start with sdk-v 2. Valid: sdk-v0.6.0, sdk-v1.0.0 3. Invalid: v0.6.0, 0.6.0, release-0.6.0

Build fails¶

Cause: Invalid pyproject.toml or missing dependencies

Solution: 1. Test locally: cd sdk && python -m build 2. Check for syntax errors in pyproject.toml 3. Verify all dependencies listed 4. Check Python version compatibility

Can't install published package¶

Cause: GitHub Packages authentication not configured

Solution: 1. Configure GitHub PAT with read:packages scope 2. Create ~/.pypirc with credentials:

[distutils]
index-servers =
    github

[github]
repository = https://pypi.pkg.github.com/Fintama
username = YOUR_GITHUB_USERNAME
password = YOUR_GITHUB_TOKEN

3. Try: pip install --no-cache-dir swisper-studio-sdk==0.6.0 --index-url https://pypi.pkg.github.com/Fintama/simple/ 4. Verify access to Fintama organization 5. See SWISPER_TEAM_HANDOVER_SDK_UPGRADE.md for detailed setup

📋 Checklist¶

Pre-Release: - [ ] Version number updated in pyproject.toml - [ ] CHANGELOG updated with changes - [ ] README updated (if needed) - [ ] All tests passing locally - [ ] Breaking changes documented - [ ] Migration guide created (if MAJOR bump)

Release: - [ ] Changes committed and pushed to main - [ ] Tag created with sdk-v{VERSION} format - [ ] Tag pushed to origin - [ ] Workflow completed successfully - [ ] PyPI page shows new version - [ ] GitHub release created

Post-Release: - [ ] Installation tested (with GitHub Packages auth) - [ ] Imports verified - [ ] Swisper team notified - [ ] Update SWISPER_TEAM_HANDOVER_SDK_UPGRADE.md if auth changed - [ ] Documentation updated

🎯 Quick Reference¶

Publish Checklist (TL;DR)¶

# 1. Update version
vim sdk/pyproject.toml  # Change version = "0.6.0"
vim sdk/CHANGELOG.md    # Add release notes

# 2. Commit
git add sdk/
git commit -m "chore: bump SDK version to 0.6.0"
git push origin main

# 3. Tag and publish
git tag -a sdk-v0.6.0 -m "SDK v0.6.0"
git push origin sdk-v0.6.0

# 4. Monitor
# → Check GitHub Actions
# → Verify GitHub Packages: https://github.com/Fintama/swisper_studio/packages
# → Test: pip install swisper-studio-sdk==0.6.0 (requires GitHub auth)

📞 Support¶

Questions? - Check this guide first - Review GitHub Actions logs - Contact DevOps team - Create issue if bug in workflow

Last Updated: 2025-11-08
Maintained By: SwisperStudio Team