diff --git a/.github/workflows/auto-approve-docs-sync.yml b/.github/workflows/auto-approve-docs-sync.yml index 178d4867..66fd93cf 100644 --- a/.github/workflows/auto-approve-docs-sync.yml +++ b/.github/workflows/auto-approve-docs-sync.yml @@ -16,10 +16,10 @@ jobs: runs-on: ubuntu-latest if: > github.event.pull_request.user.login == 'serverpod-cloud-docs-sync[bot]' && - contains(fromJSON('["auto/cli-docs-sync", "auto/framework-cli-docs-sync"]'), github.event.pull_request.head.ref) + contains(fromJSON('["auto/cli-docs-sync", "auto/framework-cli-docs-sync", "auto/dart-versions-sync"]'), github.event.pull_request.head.ref) steps: - name: Approve PR - run: gh pr review "$PR_URL" --approve --body 'Auto-approved CLI reference docs sync PR.' + run: gh pr review "$PR_URL" --approve --body 'Auto-approved docs sync PR.' env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} PR_URL: ${{ github.event.pull_request.html_url }} diff --git a/cloud_docs/reference/dart-sdk-versions.json b/cloud_docs/reference/dart-sdk-versions.json new file mode 100644 index 00000000..c954cbde --- /dev/null +++ b/cloud_docs/reference/dart-sdk-versions.json @@ -0,0 +1,9 @@ +{ + "supportedVersions": [ + "3.8", + "3.9", + "3.10", + "3.11" + ], + "defaultVersion": "3.8" +} diff --git a/cloud_docs/reference/dart-sdk-versions.md b/cloud_docs/reference/dart-sdk-versions.md deleted file mode 100644 index 647875d8..00000000 --- a/cloud_docs/reference/dart-sdk-versions.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -sidebar_position: 1 -title: Dart SDK versions -description: Which Dart SDK versions Serverpod Cloud supports, how the SDK version is selected for your build, and how to pin a version in pubspec.yaml. ---- - -# Dart SDK versions - -Serverpod Cloud supports specific Dart SDK versions for building and deploying your applications. Understanding how SDK versions are determined and used is important for configuring your project correctly. - -## Supported Dart SDK versions - -Serverpod Cloud supports the following Dart SDK versions: - -- **3.8.x** -- **3.9.x** -- **3.10.x** - -The supported version range is `>=3.8.0 <3.11.0`. This means your project's SDK constraint must overlap with this range to be deployable. - -## How SDK version is determined - -The SDK version used for building your application is determined from your project's `pubspec.yaml` file. Serverpod Cloud reads the `environment.sdk` constraint from your `pubspec.yaml` and uses **the lowest allowed version** from that constraint that falls within the supported range. - -### Version selection logic - -1. Serverpod Cloud reads the `sdk` constraint from your `pubspec.yaml` -2. It validates that your constraint overlaps with the supported range (`>=3.8.0 <3.11.0`) -3. It selects the **lowest version** that satisfies both: - - Your project's SDK constraint - - The supported version range - -This ensures compatibility while using the most conservative version that meets your requirements. - -## Configuring your pubspec.yaml - -Your `pubspec.yaml` must include an `environment.sdk` constraint. Here are examples of valid configurations: - -### Example 1: Minimum version constraint - -```yaml -name: my_serverpod_app - -environment: - sdk: ">=3.8.0 <4.0.0" - -dependencies: - serverpod: ^2.9.0 -``` - -**Result:** Uses Dart SDK **3.8.0** (the lowest version in the supported range) - -### Example 2: Specific minimum version - -```yaml -name: my_serverpod_app - -environment: - sdk: ">=3.9.0 <4.0.0" - -dependencies: - serverpod: ^2.9.0 -``` - -**Result:** Uses Dart SDK **3.9.0** (the lowest version that satisfies your constraint) - -### Example 3: Version range - -```yaml -name: my_serverpod_app - -environment: - sdk: ">=3.9.0 <3.11.0" - -dependencies: - serverpod: ^2.9.0 -``` - -**Result:** Uses Dart SDK **3.9.0** (the lowest version in your range) - -### Example 4: Caret constraint - -```yaml -name: my_serverpod_app - -environment: - sdk: "^3.10.0" - -dependencies: - serverpod: ^2.9.0 -``` - -**Result:** Uses Dart SDK **3.10.0** (the lowest version that satisfies `^3.10.0`, which is `>=3.10.0 <4.0.0`) - -### Example 5: Exact version (not recommended) - -```yaml -name: my_serverpod_app - -environment: - sdk: "3.9.5" - -dependencies: - serverpod: ^2.9.0 -``` - -**Result:** Uses Dart SDK **3.9.5** (if available, otherwise the closest supported version) - -## Invalid SDK constraints - -The following constraints will cause deployment to fail: - -### Too old - -```yaml -environment: - sdk: ">=3.7.0 <4.0.0" # ❌ 3.7.0 is below the minimum supported version -``` - -### Too new - -```yaml -environment: - sdk: ">=3.11.0 <4.0.0" # ❌ 3.11.0 is above the maximum supported version -``` - -### No overlap - -```yaml -environment: - sdk: ">=3.0.0 <3.8.0" # ❌ No overlap with supported range (>=3.8.0 <3.11.0) -``` - -## Best practices - -1. **Use a range that includes supported versions**: Specify `>=3.8.0 <4.0.0` or a narrower range like `>=3.9.0 <3.11.0` to ensure compatibility - -2. **Be specific about minimum requirements**: If your code requires features from Dart 3.9, use `>=3.9.0` to ensure the correct version is used - -3. **Avoid overly restrictive constraints**: Using exact versions like `3.9.5` can cause issues if that specific patch version isn't available - -4. **Keep constraints up to date**: As Serverpod Cloud adds support for newer Dart versions, you can update your constraints accordingly - -## Troubleshooting - -### Deployment fails with "Unsupported SDK Version" - -If you see an error like: - -``` -Unsupported sdk version constraint in package my_app: >=3.7.0 <4.0.0 -``` - -Update your `pubspec.yaml` to use a supported SDK version: - -```yaml -environment: - sdk: ">=3.8.0 <4.0.0" -``` - -### Missing SDK constraint - -If you see an error like: - -``` -No sdk constraint found in package my_app -``` - -Add an `environment.sdk` field to your `pubspec.yaml`: - -```yaml -environment: - sdk: ">=3.8.0 <4.0.0" -``` - -## Related documentation - -- [Deployments](/cloud/concepts/deployments) - Deploy operations, status checks, package validation, and `.scloudignore` configuration. -- [Private dependencies](/cloud/reference/private-dependencies) for managing workspace dependencies. diff --git a/cloud_docs/reference/dart-sdk-versions.mdx b/cloud_docs/reference/dart-sdk-versions.mdx new file mode 100644 index 00000000..0d799b42 --- /dev/null +++ b/cloud_docs/reference/dart-sdk-versions.mdx @@ -0,0 +1,75 @@ +--- +sidebar_position: 1 +title: Dart SDK versions +description: Which Dart SDK versions Serverpod Cloud supports, and how to select the version your deploy builds with using the --dart-version flag, scloud.yaml, .tool-versions, or your pubspec constraint. +--- + +import versionData from './dart-sdk-versions.json'; + +# Dart SDK versions + +Serverpod Cloud builds your server with one of a fixed set of Dart SDK versions. This page lists the supported versions and shows how to select the one your deploy uses. + +## Supported versions + + + +## How the version is selected + +The `scloud deploy` command reads the Dart SDK version from the first of these sources that sets one: + +1. The `--dart-version` flag. +2. The `dartSdk` field in `scloud.yaml`. +3. The `dart` entry in a `.tool-versions` file, in the project directory first and then the workspace root. +4. The `environment.sdk` constraint in `pubspec.yaml`. + +Every source accepts an exact version or a pub-style version constraint, such as `3.10`, `^3.9.0`, or `>=3.9.0 <4.0.0`. Serverpod Cloud builds with the highest supported version the constraint allows. If the constraint allows no supported version, the deploy fails with an error that lists the supported versions. + +When no source sets a version, your server builds with Dart {versionData.defaultVersion}. + +### Pass the flag + +```bash +# Deploy with a one-off Dart SDK version override +scloud deploy --dart-version 3.10 +``` + +### Set the version in scloud.yaml + +```yaml title="scloud.yaml" +project: + projectId: "my-app" + dartSdk: "3.10" +``` + +### Use your version manager's pin + +Version managers such as mise and asdf pin tool versions in a `.tool-versions` file. Serverpod Cloud reads the `dart` entry: + +```text title=".tool-versions" +dart 3.10.4 +``` + +### Use the pubspec constraint + +Without any of the sources above, the SDK constraint in your `pubspec.yaml` decides: + +```yaml title="pubspec.yaml" +environment: + sdk: ">=3.9.0 <4.0.0" +``` + +This example builds with the highest supported version, since the constraint allows all of them from 3.9 up. + +## Related documentation + +- [scloud.yaml schema](/cloud/reference/scloud-yaml-schema) - The `dartSdk` field and how scloud commands preserve it. +- [Deployments](/cloud/concepts/deployments) - Deploy operations, status checks, and package validation. +- [`scloud deploy`](/cloud/reference/cli/commands/deploy) - The deploy command and its flags. diff --git a/cloud_docs/reference/scloud-yaml-schema.md b/cloud_docs/reference/scloud-yaml-schema.md index 74dfa63a..faa9c2d5 100644 --- a/cloud_docs/reference/scloud-yaml-schema.md +++ b/cloud_docs/reference/scloud-yaml-schema.md @@ -50,7 +50,7 @@ project: **Type:** string. **Optional.** -Pins the Dart SDK version used for builds. When unset, scloud reads `environment.sdk` from your `pubspec.yaml` and uses the lowest version in the supported range. See [Dart SDK versions](/cloud/reference/dart-sdk-versions) for the supported versions. +Pins the Dart SDK version used for builds. When unset, scloud falls back to your `.tool-versions` file and then the `environment.sdk` constraint in your `pubspec.yaml`. See [Dart SDK versions](/cloud/reference/dart-sdk-versions) for the supported versions and the full selection order. ```yaml title="scloud.yaml" project: