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:

     bashCopy

     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 "[email protected]"
RUN apk add --update --no-cache openssh-client github-cli

Replace:

• your_github_token_here with your GitHub personal access token (with appropriate permissions)
• [email protected] 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

Reference

Configuration Files

SDK configurations are defined in the following files:

• app/config/platforms.php - Platform and SDK definitions, including metadata, Git repository URLs, versions, and enabled/disabled status
• src/Appwrite/Platform/Tasks/SDKs.php - SDK generation and release logic
• docs/sdks/<sdk-name>/CHANGELOG.md - Changelog files for each SDK

Troubleshooting

Authentication Issues

If you encounter authentication problems:

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

Common Issues

• "Release already exists" - The script automatically skips releases that already exist for the specified version
• "No changes detected" - Ensure you've updated the specs and that there are actual API changes to generate
• Permission denied - Verify that your GitHub token and SSH keys have write access to the SDK repositories

Summary

Congrats! You've successfully learned how to release Appwrite SDKs. Remember to:

1. Update SDK generator and run composer update
2. Configure Docker secrets (GitHub token and SSH keys)
3. Update specs for both latest and stable versions
4. Update changelogs and bump versions in platforms.php
5. Run the SDK script and create PRs
6. (Maintainers only) Create GitHub releases after PR approval

Happy releasing! 🎉