appwrite/docs/tutorials/release-sdks.md

Releasing Appwrite SDKs

This document is part of the Appwrite contributors' guide. Before you continue reading this document, make sure you have read the Code of Conduct and the Contributing Guide.

Getting Started

Agenda

This tutorial will cover how to properly release one or multiple Appwrite SDKs. The SDK release process involves updating the SDK generator, configuring Docker secrets, and running the release script.

Prerequisites

Before releasing SDKs, you need to:

1. Release a new SDK generator version - Create a PR in the sdk-generator repository with your respective sdk's changes. Wait for the PR to get merged and be released.

2. Update the SDK generator dependency

   • Update composer dependencies to use the new SDK generator version:

     docker run --rm --interactive --tty --volume "$(pwd)":/app composer update --ignore-platform-reqs --optimize-autoloader --no-scripts
     

   • Verify that composer.lock reflects the new SDK generator version

Configure Docker Secrets

To enable SDK releases via GitHub, you need to mount SSH keys and configure GitHub authentication in your Docker environment.

Update Dockerfile

Add the following configuration to your Dockerfile:

ARG GH_TOKEN
ENV GH_TOKEN=your_github_token_here
RUN git config --global user.email "your-email@example.com"
RUN apk add --update --no-cache openssh-client github-cli

Replace:

• your_github_token_here with your GitHub personal access token (with appropriate permissions)
• your-email@example.com with your Git email address

Update docker-compose.yml

Add the SSH key volume mount to the appwrite service in docker-compose.yml:

services:
  appwrite:
    volumes:
      - ~/.ssh:/root/.ssh
      # ... other volumes

This mounts your SSH keys from the host machine, allowing the container to authenticate with GitHub.

Updating Specs

The SDK generator script heavily relies on API specification files (specs). Whenever you are adding a new endpoint, updating parameters, or making any API changes, you need to update the specs.

Generate specs for the latest version:

docker compose exec appwrite specs

Also generate specs for the current stable Appwrite version:

docker compose exec appwrite specs --version=1.8.x

Running the SDK Release Script

Before running the SDK release script, ensure you update the following for each SDK you plan to release:

1. Update the changelog - Add release notes to the SDK's CHANGELOG.md file (located in docs/sdks/<sdk-name>/CHANGELOG.md)
2. Bump the version - Update the version number (patch, minor, or major) in app/config/platforms.php

Once you have completed these updates, run the SDK release script:

docker compose exec appwrite sdks

The script will prompt you for:

1. Platform - Select client, server, console, or * for all platforms
2. SDK(s) - Choose specific SDK(s) or * for all
3. Appwrite version - Specify the version (e.g., 1.8.x)
4. Git options - Configure push settings and PR creation

Releasing Multiple SDKs

If you are releasing multiple SDKs across different platforms, you can specify them directly:

docker compose exec appwrite sdks --sdks=dart,flutter,cli,python

Pull Request Summary

After the script completes, you'll receive a summary of created pull requests:

Pull Request Summary
Dart: https://github.com/appwrite/sdk-for-dart/pull/123
Flutter: https://github.com/appwrite/sdk-for-flutter/pull/124
CLI: https://github.com/appwrite/sdk-for-cli/pull/125

Creating GitHub Releases

Note: This section is for Appwrite maintainers only.

After the PRs have been reviewed and merged by an Appwrite Lead, you can create GitHub releases automatically.

Dry Run

First, perform a dry run to preview the releases:

docker compose exec appwrite sdks --release=yes

This will display what releases would be created:

[DRY RUN] Would create release for Dart SDK:
  Repository: appwrite/sdk-for-dart
  Version: 13.0.0
  Title: 13.0.0
  Target Branch: main
  Previous Version: 12.0.2
  Release Notes:
  ## What's Changed
  - Added support for new Users API endpoints
  - Fixed authentication token handling
  - Updated dependencies

Execute Release

After verifying the dry run output, create the actual releases:

docker compose exec appwrite sdks --release=yes --commit=yes

Release Configuration Reference

SDK configurations are defined in:

• Platform and SDK definitions: app/config/collections/platform.php
• SDK generation logic: src/Appwrite/Platform/Tasks/SDKs.php

These files contain the SDK metadata, Git repository URLs, versions, and other configuration needed for the release process.

Troubleshooting

If you encounter authentication issues:

• Verify your GitHub token has the correct permissions (repo access, workflow permissions)
• Ensure your SSH keys are properly configured in ~/.ssh/
• Check that the Git email in the Dockerfile matches your GitHub account

If everything went well, you should see the SDKs being generated and pushed to their respective repositories.

Congrats! You have successfully released Appwrite SDKs. 🎉