docs

.github/workflows/build_and_deploy.yml

@@ -1,3 +1,4 @@
+# Update all mentions of this name in vercel-packages when changing.
 name: build-and-deploy
 
 on:
@@ -472,6 +473,7 @@ jobs:
       - name: Upload tarballs
         uses: actions/upload-artifact@v4
         with:
+          # Update all mentions of this name in vercel-packages when changing.
           name: preview-tarballs
           path: ${{ runner.temp }}/preview-tarballs/*
 

contributing/core/testing.md

@@ -128,21 +128,20 @@ TURBOPACK=1 pnpm test-dev test/e2e/app-dir/app/
 
 ## Integration testing outside the repository with preview builds
 
-Every branch build will create a tarball of Next.js that can be used in external repositories.
+Every branch build will create a tarball for each package in this repository<sup>1</sup> that can be used in external repositories.
 
 You can use this preview build in other packages by using a https://vercel-packages.vercel.app URL instead of a version in the `package.json` e.g.
 
 ```json
 {
   "dependencies": {
-    "next": "https://vercel-packages.vercel.app/next/prs/12345/packages/next"
+    "next": "https://vercel-packages.vercel.app/next/commits/abcd/next"
   }
 }
 ```
 
-You can refer to builds by commit SHA or PR number.
+You can refer to builds only by commit SHAs at the moment.
 
-These all work as expected:
-
-- https://vercel-packages.vercel.app/next/prs/12345/packages/next
-- https://vercel-packages.vercel.app/next/commits/12345/packages/next
+<sup>1</sup> Not all native packages are built automatically.
+`build-and-deploy` excludes slow, rarely used native variants of `next-swc`.
+To force a build of all packages, you can trigger `build-and-deploy` manually (i.e. `workflow_dispatch`).

scripts/create-preview-tarballs.js

@@ -74,7 +74,7 @@ async function main() {
         path.join(nativePackagesDir, platform, 'package.json'),
         JSON.stringify(manifest, null, 2) + '\n'
       )
-      // By encoding the package name in the directory, we can later extract the package name of a tarball from its path when `tarballDirectory` is zipped.
+      // By encoding the package name in the directory, vercel-packages can later extract the package name of a tarball from its path when `tarballDirectory` is zipped.
       const packDestination = path.join(tarballDirectory, manifest.name)
       await fs.mkdir(packDestination, { recursive: true })
       const { stdout } = await execa(
@@ -156,7 +156,7 @@ async function main() {
         '\n'
     )
 
-    // By encoding the package name in the directory, we can later extract the package name of a tarball from its path when `tarballDirectory` is zipped.
+    // By encoding the package name in the directory, vercel-packages can later extract the package name of a tarball from its path when `tarballDirectory` is zipped.
     const packDestination = path.join(tarballDirectory, manifest.name)
     await fs.mkdir(packDestination, { recursive: true })
     const { stdout } = await execa(