From fce4f72ca92a09ac78c46b37098197684c70eaf7 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Fri, 31 Oct 2025 17:18:54 +0530 Subject: [PATCH 1/3] doc: add tutorial for releasing sdks --- docs/tutorials/release-sdks.md | 151 +++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 docs/tutorials/release-sdks.md diff --git a/docs/tutorials/release-sdks.md b/docs/tutorials/release-sdks.md new file mode 100644 index 0000000000..9b9185ea3b --- /dev/null +++ b/docs/tutorials/release-sdks.md @@ -0,0 +1,151 @@ +# 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](https://github.com/appwrite/.github/blob/main/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). + +## 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](https://github.com/appwrite/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: + ```bash + 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`: + +```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`: + +```yaml +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 + +SDK generator script heavily relies on specs. So whenever you are adding a new endpoint, updating parameters or making any sort of API changes, you need to update the specs. You can do this by running the following command: + +```bash +docker compose exec appwrite specs +``` + +Make sure to also run it for the current Appwrite version. + +```bash +docker compose exec appwrite specs --version=1.8.x +``` + +### Running the SDK Release Script + +Before running the SDK release script you need to make sure to update 2 things for the respective SDKs you plan to release: + +1. Update the changelog in the respective SDK's `CHANGELOG.md` file. +2. Bump the version (patch, minor or major) in the `platforms.php` file. + +Once you have done that, you can run the SDK release script using the following command: + +```bash +docker compose exec appwrite sdks +``` + +The script will: +1. Prompt you to select the platform (client, server, console, or `*` for all) +2. Ask which SDK(s) to generate (or `*` for all) +3. Request the Appwrite version for which to generate the SDKs (For example: 1.8.x) +4. Guide you through git push options and PR creation + +If you are releasing multiple SDKs that belong to different platforms, you can pass in the array of SDKs manually like this: + +```bash +docker compose exec appwrite sdks --sdks=dart,flutter,cli,python +``` + +Once you have run the SDK release script, you will get a summary of the PRs made like this: + +```text +Pull Request Summary +Dart: https://github.com/appwrite/dart-sdk/pull/123 +Flutter: https://github.com/appwrite/flutter-sdk/pull/123 +``` + +### Releasing the SDKs + +If you are a maintainer at Appwrite, you can release the SDKs automatically by using the script. Before that make sure the PRs are reviewed and merged by a Lead at Appwrite. + +```bash +docker compose exec appwrite sdks --release=yes +``` + +This will give a DRY RUN for how the releases will look like: + +```text +[DRY RUN] Would create release for Dart SDK: + Repository: appwrite/dart-sdk + Version: 1.8.0 + Title: 1.8.0 + Target Branch: main + Previous Version: 1.7.0 + Release Notes: + ## What's Changed + - Add new endpoint /users/:userId/logs + - Add new endpoint /users/:userId/logs +``` + +After everything looks good, you can release the SDKs by running the following command: + +```bash +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. 🎉 From 8c8073d7aa3d96217152c927b6dca548730e1b00 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Fri, 31 Oct 2025 17:22:02 +0530 Subject: [PATCH 2/3] grammer fixes --- docs/tutorials/release-sdks.md | 68 +++++++++++++++++++++------------- 1 file changed, 42 insertions(+), 26 deletions(-) diff --git a/docs/tutorials/release-sdks.md b/docs/tutorials/release-sdks.md index 9b9185ea3b..cd3311e117 100644 --- a/docs/tutorials/release-sdks.md +++ b/docs/tutorials/release-sdks.md @@ -55,15 +55,17 @@ services: This mounts your SSH keys from the host machine, allowing the container to authenticate with GitHub. -### Updating specs +### Updating Specs -SDK generator script heavily relies on specs. So whenever you are adding a new endpoint, updating parameters or making any sort of API changes, you need to update the specs. You can do this by running the following command: +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: ```bash docker compose exec appwrite specs ``` -Make sure to also run it for the current Appwrite version. +Also generate specs for the current stable Appwrite version: ```bash docker compose exec appwrite specs --version=1.8.x @@ -71,61 +73,75 @@ docker compose exec appwrite specs --version=1.8.x ### Running the SDK Release Script -Before running the SDK release script you need to make sure to update 2 things for the respective SDKs you plan to release: +Before running the SDK release script, ensure you update the following for each SDK you plan to release: -1. Update the changelog in the respective SDK's `CHANGELOG.md` file. -2. Bump the version (patch, minor or major) in the `platforms.php` file. +1. **Update the changelog** - Add release notes to the SDK's `CHANGELOG.md` file (located in `docs/sdks//CHANGELOG.md`) +2. **Bump the version** - Update the version number (patch, minor, or major) in `app/config/platforms.php` -Once you have done that, you can run the SDK release script using the following command: +Once you have completed these updates, run the SDK release script: ```bash docker compose exec appwrite sdks ``` -The script will: -1. Prompt you to select the platform (client, server, console, or `*` for all) -2. Ask which SDK(s) to generate (or `*` for all) -3. Request the Appwrite version for which to generate the SDKs (For example: 1.8.x) -4. Guide you through git push options and PR creation +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 -If you are releasing multiple SDKs that belong to different platforms, you can pass in the array of SDKs manually like this: +#### Releasing Multiple SDKs + +If you are releasing multiple SDKs across different platforms, you can specify them directly: ```bash docker compose exec appwrite sdks --sdks=dart,flutter,cli,python ``` -Once you have run the SDK release script, you will get a summary of the PRs made like this: +#### Pull Request Summary + +After the script completes, you'll receive a summary of created pull requests: ```text Pull Request Summary -Dart: https://github.com/appwrite/dart-sdk/pull/123 -Flutter: https://github.com/appwrite/flutter-sdk/pull/123 +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 ``` -### Releasing the SDKs +### Creating GitHub Releases -If you are a maintainer at Appwrite, you can release the SDKs automatically by using the script. Before that make sure the PRs are reviewed and merged by a Lead at Appwrite. +> **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: ```bash docker compose exec appwrite sdks --release=yes ``` -This will give a DRY RUN for how the releases will look like: +This will display what releases would be created: ```text [DRY RUN] Would create release for Dart SDK: - Repository: appwrite/dart-sdk - Version: 1.8.0 - Title: 1.8.0 + Repository: appwrite/sdk-for-dart + Version: 13.0.0 + Title: 13.0.0 Target Branch: main - Previous Version: 1.7.0 + Previous Version: 12.0.2 Release Notes: ## What's Changed - - Add new endpoint /users/:userId/logs - - Add new endpoint /users/:userId/logs + - Added support for new Users API endpoints + - Fixed authentication token handling + - Updated dependencies ``` -After everything looks good, you can release the SDKs by running the following command: +#### Execute Release + +After verifying the dry run output, create the actual releases: ```bash docker compose exec appwrite sdks --release=yes --commit=yes From ebee3536f59dd56b48a98310d613e6e539e90662 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Fri, 31 Oct 2025 17:24:03 +0530 Subject: [PATCH 3/3] final changes --- docs/tutorials/release-sdks.md | 41 +++++++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 11 deletions(-) diff --git a/docs/tutorials/release-sdks.md b/docs/tutorials/release-sdks.md index cd3311e117..99c0fa4fd3 100644 --- a/docs/tutorials/release-sdks.md +++ b/docs/tutorials/release-sdks.md @@ -147,21 +147,40 @@ After verifying the dry run output, create the actual releases: docker compose exec appwrite sdks --release=yes --commit=yes ``` -### Release Configuration Reference +## Reference -SDK configurations are defined in: -- **Platform and SDK definitions**: `app/config/collections/platform.php` -- **SDK generation logic**: `src/Appwrite/Platform/Tasks/SDKs.php` +### Configuration Files -These files contain the SDK metadata, Git repository URLs, versions, and other configuration needed for the release process. +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//CHANGELOG.md`** - Changelog files for each SDK ## 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 +### Authentication Issues -If everything went well, you should see the SDKs being generated and pushed to their respective repositories. +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 -Congrats! You have successfully released Appwrite SDKs. 🎉 +### 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! 🎉