Merge pull request #482 from actions/robherley/add-migration-docs

Add migrations docs

.github/workflows/check-dist.yml

@@ -46,7 +46,7 @@ jobs:
         id: diff
 
       # If index.js was different than expected, upload the expected version as an artifact
-      - uses: actions/upload-artifact@v4-beta
+      - uses: actions/upload-artifact@v4
         if: ${{ failure() && steps.diff.conclusion == 'failure' }}
         with:
           name: dist

.github/workflows/test.yml

@@ -81,7 +81,7 @@ jobs:
 
     # Download Artifact #1 and verify the correctness of the content
     - name: 'Download artifact #1'
-      uses: actions/download-artifact@v4-beta
+      uses: actions/download-artifact@v4
       with:
         name: 'Artifact-A-${{ matrix.runs-on }}'
         path: some/new/path
@@ -101,7 +101,7 @@ jobs:
 
     # Download Artifact #2 and verify the correctness of the content
     - name: 'Download artifact #2'
-      uses: actions/download-artifact@v4-beta
+      uses: actions/download-artifact@v4
       with:
         name: 'Artifact-Wildcard-${{ matrix.runs-on }}'
         path: some/other/path
@@ -122,7 +122,7 @@ jobs:
 
     # Download Artifact #4 and verify the correctness of the content
     - name: 'Download artifact #4'
-      uses: actions/download-artifact@v4-beta
+      uses: actions/download-artifact@v4
       with:
         name: 'Multi-Path-Artifact-${{ matrix.runs-on }}'
         path: multi/artifact

README.md

@@ -56,6 +56,8 @@ For more information, see the [`@actions/artifact`](https://github.com/actions/t
 
 3. Limit of Artifacts for an individual job. Each job in a workflow run now has a limit of 10 artifacts.
 
+For assistance with breaking changes, see [MIGRATION.md](docs/MIGRATION.md).
+
 ## Usage
 
 ### Inputs
@@ -271,7 +273,7 @@ You can use `~` in the path input as a substitute for `$HOME`. Basic tilde expan
       echo hello > ~/new/artifact/world.txt
   - uses: actions/upload-artifact@v4
     with:
-      name: Artifacts-V4-beta
+      name: my-artifacts
       path: ~/new/**/*
 ```
 

docs/MIGRATION.md

@@ -0,0 +1,80 @@
+# Migration
+
+- [Migration](#migration)
+  - [Multiple uploads to the same named Artifact](#multiple-uploads-to-the-same-named-artifact)
+
+Several behavioral differences exist between Artifact actions `v3` and below vs `v4`. This document outlines common scenarios in `v3`, and how they would be handled in `v4`.
+
+## Multiple uploads to the same named Artifact
+
+In `v3`, Artifacts are _mutable_ so it's possible to write workflow scenarios where multiple jobs upload to the same Artifact like so:
+
+```yaml
+jobs:
+  upload:
+    strategy:
+      matrix:
+        runs-on: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.runs-on }}
+    steps:
+      - name: Create a File
+        run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: my-artifact # NOTE: same artifact name
+          path: file-${{ matrix.runs-on }}.txt
+  download:
+    needs: upload
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download All Artifacts
+        uses: actions/download-artifact@v3
+        with:
+          path: my-artifact
+      - run: ls -R my-artifact
+```
+
+This results in a directory like so:
+
+```
+my-artifact/
+  file-macos-latest.txt
+  file-ubuntu-latest.txt
+  file-windows-latest.txt
+```
+
+In v4, Artifacts are immutable (unless deleted). So you must change each of the uploaded Artifacts to have a different name and filter the downloads by name to achieve the same effect:
+
+```diff
+jobs:
+  upload:
+    strategy:
+      matrix:
+        runs-on: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.runs-on }}
+    steps:
+    - name: Create a File
+      run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
+    - name: Upload Artifact
+-     uses: actions/upload-artifact@v3
++     uses: actions/upload-artifact@v4
+      with:
+-       name: my-artifact
++       name: my-artifact-${{ matrix.runs-on }}
+        path: file-${{ matrix.runs-on }}.txt
+  download:
+    needs: upload
+    runs-on: ubuntu-latest
+    steps:
+    - name: Download All Artifacts
+-     uses: actions/download-artifact@v3
++     uses: actions/download-artifact@v4
+      with:
+        path: my-artifact
++       pattern: my-artifact-*
++       merge-multiple: true
+    - run: ls -R my-artifact
+```
+
+In `v4`, the new `pattern:` input will filter the downloaded Artifacts to match the name specified. The new `merge-multiple:` input will support downloading multiple Artifacts to the same directory. If the files within the Artifacts have the same name, the last writer wins.

src/upload-artifact.ts

@@ -1,7 +1,5 @@
-import * as core from '../node_modules/@actions/core/'
+import * as core from '@actions/core'
-import artifact, {
+import artifact, {UploadArtifactOptions} from '@actions/artifact'
-  UploadArtifactOptions
-} from '../node_modules/@actions/artifact/lib/artifact'
 import {findFilesToUpload} from './search'
 import {getInputs} from './input-helper'
 import {NoFileOptions} from './constants'