Merge pull request dart-archive#14 from dart-lang/mit-mit-patch-1

Merge to main
mit-mit · Jan 19, 2021 · db4ae86 · db4ae86
2 parents b705214 + 85bd261
commit db4ae86
Show file tree

Hide file tree

Showing 2 changed files with 74 additions and 13 deletions.
diff --git a/.github/workflows/dart.yml b/.github/workflows/dart.yml
@@ -13,7 +13,9 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        sdk: [stable, 2.7.2, 2.12.0-133.7.beta, beta, dev ]
+        # Test latest stable, beta, and dev channels + last stable release
+        # prior to the introduction of the unified `dart` developer tool.
+        sdk: [stable, beta, dev, 2.9.3, 2.12.0-29.10.beta]
     steps:
       - uses: actions/checkout@v2
       - uses: ./
@@ -25,6 +27,7 @@ jobs:
           echo "main() { print('hello world'); }" > hello.dart
           dart hello.dart
 
+  # TODO: Remove this step after v0.2 (https://github.com/dart-lang/setup-dart/issues/12).
   test_deprecated_channel:
     runs-on: ubuntu-latest
     strategy:

diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ This [GitHub Action]() installs and sets up of a Dart SDK for use in actions by:
 
 Install the latest stable SDK, and run Hello World.
 
-```
+```yml
 name: Dart
 
 on:
@@ -45,7 +45,7 @@ Various static checks:
   2) Check code follows Dart idiomatic formatting
   3) Check that unit tests pass
 
-```
+```yml
 ...
     steps:
 
@@ -64,12 +64,15 @@ Various static checks:
 
 ## Matrix testing
 
-Double matrix across two dimensions:
+You can create matrix jobs that run tests on multiple operating systems, and
+multiple versions of the Dart SDK.
+
+The following example create a double matrix across two dimensions:
 
   - All three major operating systems: Linux, macOS, and Windows.
-  - Dart SDK: stable, beta, dev, or a specific version string.
+  - Five Dart SDKs: Latest stable, beta & dev plus two specific versions.
 
-```
+```yml
 name: Dart
 
 on:
@@ -84,25 +87,80 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        sdk: [stable, 2.7.2, 2.12.0-1.4.beta, beta, dev]
+        sdk: [stable, beta, dev, 2.10.3, 2.12.0-29.10.beta]
     steps:
       - uses: actions/checkout@v2
       - uses: dart-lang/setup-dart@v1
         with:
           sdk: ${{ matrix.sdk }}
 
       - name: Install dependencies
-        run: pub get
+        run: dart pub get
 
+      - name: Run tests
+        run: dart test
+```
+
+## Testing older Dart SDKs
+
+The Dart SDK continously evolves, and new features and tools are added. The Dart
+2.10 SDK introduced a new unified `dart` developer tool, which is what we use in
+the usage examples above for installing dependencies, verifying formatting,
+analyzing, etc. If you need to test a combination of SDKs before and after Dart
+2.10, we recommend splitting your test job as illustrated here:
+
+```yml
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        sdk: [stable, beta, dev]
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dart-lang/setup-dart@main
+        with:
+          sdk: ${{ matrix.sdk }}
+      - name: Install dependencies
+        run: dart pub get
+      - name: Check formatting
+        run: dart format --output=none --set-exit-if-changed .
+      - name: Analyze code
+        run: dart analyze
+      - name: Run tests
+        run: dart test
+
+  test_old_sdks:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        sdk: [2.9.0, 2.8.1]
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dart-lang/setup-dart@main
+        with:
+          sdk: ${{ matrix.sdk }}
+      - name: Install dependencies
+        run: pub get
+      - name: Check formatting
+        run: dartfmt --dry-run --set-exit-if-changed .
+      - name: Analyze code
+        run: dartanalyzer --fatal-warnings .
       - name: Run tests
         run: pub run test
 ```
 
-> __NOTE:__ The above example is using the deprecated global `pub` executable instead of `dart pub` - which was released in `2.12.0`.
-> 
-> When specifying a version that precedes the `2.12.0` release _(like `2.7.2` from the above example)_ - the commands need to work across all versions in the matrix.
-> 
-> If you are not testing version(s) that precede the `2.12.0` release, use `dart pub get` / `dart test` instead of `pub get` / `pub run test`.
+# Version history
+
+## v0.2
+
+  * Added support for installing a specific SDK version (e.g. `2.10.0`).
+
+## v0.1
+
+  * Initial version.
 
 # License