readme & error updates

packages/artifact/README.md

@@ -1,13 +1,57 @@
 # `@actions/artifact`
 
-## Usage
+Interact programmatically with [Actions Artifacts](https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts).
 
-You can use this package to interact with the Actions artifacts.
+This is the core library that powers the [`@actions/upload-artifact`](https://github.com/actions/upload-artifact) and [`@actions/download-artifact`](https://github.com/actions/download-artifact) actions.
 
-This most recently published version of this package (`1.1.1`) can be found [here](https://github.com/actions/toolkit/tree/@actions/artifact@1.1.1/packages/artifact)
 
-## 🚧 Under construction 🚧
+- [`@actions/artifact`](#actionsartifact)
+  - [v2 - Major Performance and Behavioral Improvements](#v2---major-performance-and-behavioral-improvements)
+    - [Improvements](#improvements)
+    - [Breaking changes](#breaking-changes)
+  - [Example scenarios](#example-scenarios)
+    - [Basic Upload and Download](#basic-upload-and-download)
+    - [Using `actions/github-script`](#using-actionsgithub-script)
+    - [Downloading from other runs or repos](#downloading-from-other-runs-or-repos)
+    - [Speeding up large uploads](#speeding-up-large-uploads)
 
-This package is currently undergoing a major overhaul in preparation for `v4` versions of `upload-artifact` and `download-artifact` (these Actions will use a new `2.0.0` version of `@actions/artifact` that will soon be released). The upcoming version of `@actions/artifact` will take advantage of a major re-architecture with entirely new APIs.
 
-The upcoming `2.0.0` package and `v4` artifact Actions aim to solve some of the major pain-points that have made artifact usage difficult up until now.
+## v2 - Major Performance and Behavioral Improvements
+
+> [!IMPORTANT]
+> @actions/artifact v2+, download-artifact@v4+ download-artifact@v4+ are not currently supported on GHES yet. The previous version of this package can be found at [this tag](https://github.com/actions/toolkit/tree/@actions/artifact@1.1.2/packages/artifact) and [on npm](https://www.npmjs.com/package/@actions/artifact/v/1.1.2).
+
+The release of `@actions/artifact@v2` (including `download-artifact@v4` and `download-artifact@v4`) are major changes to the backend architecture of Artifacts. They have numerous performance and behavioral improvements.
+
+### Improvements
+
+1. All upload and download operations are exponentially faster, up to 80% faster download times and 96% faster upload times in worst case scenarios.
+2. Once uploaded, Artifacts becoming immediately available in the UI and [REST API](https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28). Previously, you would have to wait for the run to be completed.
+3. Artifacts are _immutable_ once they are uploaded. They cannot be altered by subsequent jobs. (Digest/integrity hash coming soon in API!)
+4. This library (and `actions/download-artifact`) now support downloading Artifacts from _other_ repositories and runs if a `GITHUB_TOKEN` with sufficient `actions:read` permissions are provided.
+
+### Breaking changes
+
+1. Firewall rules required for self-hosted runners.
+
+    If you are using self-hosted runners behind a firewall, you must have flows open to [Actions endpoints](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#communication-between-self-hosted-runners-and-github). If you cannot use wildcard rules for your firewall, see the GitHub [meta endpoint](https://api.github.com/meta) for specific endpoints.
+
+    e.g.
+
+    ```
+    curl https://api.github.com/meta | jq .domains.actions
+    ```
+
+2. Uploading to the same named Artifact multiple times.
+
+    Due to the behavior of how Artifacts are created in this new version, it is no longer possible to upload to the same named Artifact multiple times. You must either split the uploads into multiple names Artifacts, or only upload once.
+
+## Example scenarios
+
+### Basic Upload and Download
+
+### Using `actions/github-script`
+
+### Downloading from other runs or repos
+
+### Speeding up large uploads

packages/artifact/src/internal/shared/errors.ts

@@ -29,7 +29,7 @@ export class ArtifactNotFoundError extends Error {
 
 export class GHESNotSupportedError extends Error {
   constructor(
-    message = '@actions/artifact v2.0.0+ and download-artifact@v4+ are not currently supported on GHES.'
+    message = '@actions/artifact v2.0.0+, upload-artifact@v4+ and download-artifact@v4+ are not currently supported on GHES.'
   ) {
     super(message)
     this.name = 'GHESNotSupportedError'