From 5bdd59d7a7fdfbcde32a52db5b54f37f196c89a6 Mon Sep 17 00:00:00 2001 From: Akino Date: Tue, 5 May 2026 10:56:53 +0800 Subject: [PATCH 01/80] Add a docs site for `changesets` (#1512) Co-authored-by: bluwy --- .gitignore | 1 + package.json | 8 +- pnpm-lock.yaml | 1487 +++++++++++------ pnpm-workspace.yaml | 4 + site/.vitepress/config.ts | 146 ++ site/.vitepress/theme/custom.css | 32 + site/.vitepress/theme/index.ts | 5 + site/.vitepress/theme/style.css | 138 ++ site/faq/publishing-in-monorepos.md | 5 + site/guide/advance/fixed-packages.md | 50 + site/guide/advance/linked-packages.md | 90 + .../advance/modifying-changelog-format.md | 82 + site/guide/advance/pre-releases.md | 143 ++ site/guide/advance/snapshot-releases.md | 53 + site/guide/advance/versioning-apps.md | 22 + site/guide/api/cli.md | 158 ++ site/guide/basic/adding-a-changeset.md | 71 + site/guide/basic/automating-changesets.md | 55 + site/guide/basic/checking-for-changesets.md | 13 + site/guide/basic/configuration.md | 255 +++ site/guide/intro/concepts.md | 61 + site/guide/intro/dictionary.md | 34 + site/guide/intro/getting-started.md | 90 + site/guide/intro/what-are-changesets.md | 14 + site/index.md | 35 + site/lib/apply-release-plan.md | 27 + site/lib/assemble-release-plan.md | 44 + site/lib/changelog-git.md | 1 + site/lib/changelog-github.md | 1 + site/lib/cli.md | 198 +++ site/lib/config.md | 25 + site/lib/errors.md | 7 + site/lib/get-dependents-graph.md | 16 + site/lib/get-github-info.md | 85 + site/lib/get-release-plan.md | 26 + site/lib/get-version-range-type.md | 10 + site/lib/git.md | 9 + site/lib/logger.md | 44 + site/lib/parse.md | 47 + site/lib/pre.md | 32 + site/lib/read.md | 15 + site/lib/release-utils.md | 1 + site/lib/should-skip-package.md | 1 + site/lib/types.md | 21 + site/lib/write.md | 43 + site/package.json | 15 + site/public/logo.svg | 30 + site/tsconfig.json | 14 + 48 files changed, 3270 insertions(+), 494 deletions(-) create mode 100644 site/.vitepress/config.ts create mode 100644 site/.vitepress/theme/custom.css create mode 100644 site/.vitepress/theme/index.ts create mode 100644 site/.vitepress/theme/style.css create mode 100644 site/faq/publishing-in-monorepos.md create mode 100644 site/guide/advance/fixed-packages.md create mode 100644 site/guide/advance/linked-packages.md create mode 100644 site/guide/advance/modifying-changelog-format.md create mode 100644 site/guide/advance/pre-releases.md create mode 100644 site/guide/advance/snapshot-releases.md create mode 100644 site/guide/advance/versioning-apps.md create mode 100644 site/guide/api/cli.md create mode 100644 site/guide/basic/adding-a-changeset.md create mode 100644 site/guide/basic/automating-changesets.md create mode 100644 site/guide/basic/checking-for-changesets.md create mode 100644 site/guide/basic/configuration.md create mode 100644 site/guide/intro/concepts.md create mode 100644 site/guide/intro/dictionary.md create mode 100644 site/guide/intro/getting-started.md create mode 100644 site/guide/intro/what-are-changesets.md create mode 100644 site/index.md create mode 100644 site/lib/apply-release-plan.md create mode 100644 site/lib/assemble-release-plan.md create mode 100644 site/lib/changelog-git.md create mode 100644 site/lib/changelog-github.md create mode 100644 site/lib/cli.md create mode 100644 site/lib/config.md create mode 100644 site/lib/errors.md create mode 100644 site/lib/get-dependents-graph.md create mode 100644 site/lib/get-github-info.md create mode 100644 site/lib/get-release-plan.md create mode 100644 site/lib/get-version-range-type.md create mode 100644 site/lib/git.md create mode 100644 site/lib/logger.md create mode 100644 site/lib/parse.md create mode 100644 site/lib/pre.md create mode 100644 site/lib/read.md create mode 100644 site/lib/release-utils.md create mode 100644 site/lib/should-skip-package.md create mode 100644 site/lib/types.md create mode 100644 site/lib/write.md create mode 100644 site/package.json create mode 100644 site/public/logo.svg create mode 100644 site/tsconfig.json diff --git a/.gitignore b/.gitignore index 4d46b20b6..0e62a1f14 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ node_modules/ .env *error.log scratchings.js +/site/.vitepress/cache/ diff --git a/package.json b/package.json index 8a2a98754..fb249afee 100644 --- a/package.json +++ b/package.json @@ -13,6 +13,9 @@ "test": "vitest", "types:check": "tsc", "check-all": "node --run build && node --run test -- run && node --run types:check && node --run lint && node --run format", + "docs:dev": "pnpm --filter=./site dev", + "docs:build": "pnpm --filter=./site build", + "docs:preview": "pnpm --filter=./site preview", "version-packages": "node --run changeset version && node --run format:fix", "release": "node --run build && node --run changeset publish", "changeset": "NODE_OPTIONS=--experimental-strip-types packages/cli/bin.js" @@ -24,7 +27,8 @@ "packageManager": "pnpm@11.0.4", "workspaces": [ "packages/*", - "scripts/*" + "scripts/*", + "site" ], "author": "Changesets Contributors", "contributors": [ @@ -70,4 +74,4 @@ "engines": { "node": "^22 || >=24" } -} +} \ No newline at end of file diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 64db5f876..dc7e84de1 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -5,6 +5,9 @@ settings: dedupePeers: true excludeLinksFromLockfile: false +overrides: + vitepress>vite: ^8.0.0 + importers: .: @@ -62,7 +65,7 @@ importers: version: 8.59.1(eslint@10.3.0)(typescript@6.0.3) vitest: specifier: ^4.1.5 - version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@7.2.7) + version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@8.0.10) packages/apply-release-plan: dependencies: @@ -152,7 +155,7 @@ importers: version: link:../parse vitest: specifier: ^4.1.5 - version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@7.2.7) + version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@8.0.10) packages/cli: dependencies: @@ -246,7 +249,7 @@ importers: version: 0.8.0 vitest: specifier: ^4.1.5 - version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@7.2.7) + version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@8.0.10) packages/config: dependencies: @@ -283,7 +286,7 @@ importers: version: 0.8.0 vitest: specifier: ^4.1.5 - version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@7.2.7) + version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@8.0.10) packages/errors: {} @@ -304,7 +307,7 @@ importers: version: link:../../scripts/test-utils vitest: specifier: ^4.1.5 - version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@7.2.7) + version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@8.0.10) packages/get-github-info: dependencies: @@ -378,7 +381,7 @@ importers: devDependencies: vitest: specifier: ^4.1.5 - version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@7.2.7) + version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@8.0.10) packages/parse: dependencies: @@ -478,7 +481,7 @@ importers: version: link:../write vitest: specifier: ^4.1.5 - version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@7.2.7) + version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@8.0.10) packages/should-skip-package: dependencies: @@ -512,7 +515,7 @@ importers: version: link:../../scripts/test-utils vitest: specifier: ^4.1.5 - version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@7.2.7) + version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@8.0.10) scripts/test-utils: dependencies: @@ -527,7 +530,13 @@ importers: version: 1.0.2 vitest: specifier: ^4.1.5 - version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@7.2.7) + version: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@8.0.10) + + site: + devDependencies: + vitepress: + specifier: ^2.0.0-alpha.17 + version: 2.0.0-alpha.17(@types/node@24.12.2)(postcss@8.5.13)(terser@5.44.1)(typescript@6.0.3) packages: @@ -1054,161 +1063,23 @@ packages: resolution: {integrity: sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==} engines: {node: '>=18'} - '@esbuild/aix-ppc64@0.25.12': - resolution: {integrity: sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==} - engines: {node: '>=18'} - cpu: [ppc64] - os: [aix] + '@docsearch/css@4.6.3': + resolution: {integrity: sha512-nlOwcXcsNAptQl4vlL4MA78qNJKO0Qlds5GuBjCoePgkebTXLSf8Qt1oyZ3YBshYupKXG9VRGEsk1zr23d+bzQ==} - '@esbuild/android-arm64@0.25.12': - resolution: {integrity: sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==} - engines: {node: '>=18'} - cpu: [arm64] - os: [android] - - '@esbuild/android-arm@0.25.12': - resolution: {integrity: sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==} - engines: {node: '>=18'} - cpu: [arm] - os: [android] + '@docsearch/js@4.6.3': + resolution: {integrity: sha512-qUIX2b4Apew3tv4F0qhmgShsl/Lfw4m6mqv/5/5dWNxwTcDdLMp2s3YwZ+NMGh3IKCg0pBaXm7Q5VdyU5Rj+cQ==} - '@esbuild/android-x64@0.25.12': - resolution: {integrity: sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==} - engines: {node: '>=18'} - cpu: [x64] - os: [android] + '@docsearch/sidepanel-js@4.6.3': + resolution: {integrity: sha512-grGSmvXzG0if+mrzdIKykvpIAuEQ9u0sEJ2eLRRCaQfJvsWqh2C2/aY04bIzWvDh7myi5rvl8D+tUNsVrjYQ3A==} - '@esbuild/darwin-arm64@0.25.12': - resolution: {integrity: sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==} - engines: {node: '>=18'} - cpu: [arm64] - os: [darwin] + '@emnapi/core@1.10.0': + resolution: {integrity: sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw==} - '@esbuild/darwin-x64@0.25.12': - resolution: {integrity: sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==} - engines: {node: '>=18'} - cpu: [x64] - os: [darwin] + '@emnapi/runtime@1.10.0': + resolution: {integrity: sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==} - '@esbuild/freebsd-arm64@0.25.12': - resolution: {integrity: sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==} - engines: {node: '>=18'} - cpu: [arm64] - os: [freebsd] - - '@esbuild/freebsd-x64@0.25.12': - resolution: {integrity: sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==} - engines: {node: '>=18'} - cpu: [x64] - os: [freebsd] - - '@esbuild/linux-arm64@0.25.12': - resolution: {integrity: sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==} - engines: {node: '>=18'} - cpu: [arm64] - os: [linux] - - '@esbuild/linux-arm@0.25.12': - resolution: {integrity: sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==} - engines: {node: '>=18'} - cpu: [arm] - os: [linux] - - '@esbuild/linux-ia32@0.25.12': - resolution: {integrity: sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==} - engines: {node: '>=18'} - cpu: [ia32] - os: [linux] - - '@esbuild/linux-loong64@0.25.12': - resolution: {integrity: sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==} - engines: {node: '>=18'} - cpu: [loong64] - os: [linux] - - '@esbuild/linux-mips64el@0.25.12': - resolution: {integrity: sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==} - engines: {node: '>=18'} - cpu: [mips64el] - os: [linux] - - '@esbuild/linux-ppc64@0.25.12': - resolution: {integrity: sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==} - engines: {node: '>=18'} - cpu: [ppc64] - os: [linux] - - '@esbuild/linux-riscv64@0.25.12': - resolution: {integrity: sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==} - engines: {node: '>=18'} - cpu: [riscv64] - os: [linux] - - '@esbuild/linux-s390x@0.25.12': - resolution: {integrity: sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==} - engines: {node: '>=18'} - cpu: [s390x] - os: [linux] - - '@esbuild/linux-x64@0.25.12': - resolution: {integrity: sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==} - engines: {node: '>=18'} - cpu: [x64] - os: [linux] - - '@esbuild/netbsd-arm64@0.25.12': - resolution: {integrity: sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==} - engines: {node: '>=18'} - cpu: [arm64] - os: [netbsd] - - '@esbuild/netbsd-x64@0.25.12': - resolution: {integrity: sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==} - engines: {node: '>=18'} - cpu: [x64] - os: [netbsd] - - '@esbuild/openbsd-arm64@0.25.12': - resolution: {integrity: sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==} - engines: {node: '>=18'} - cpu: [arm64] - os: [openbsd] - - '@esbuild/openbsd-x64@0.25.12': - resolution: {integrity: sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==} - engines: {node: '>=18'} - cpu: [x64] - os: [openbsd] - - '@esbuild/openharmony-arm64@0.25.12': - resolution: {integrity: sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==} - engines: {node: '>=18'} - cpu: [arm64] - os: [openharmony] - - '@esbuild/sunos-x64@0.25.12': - resolution: {integrity: sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==} - engines: {node: '>=18'} - cpu: [x64] - os: [sunos] - - '@esbuild/win32-arm64@0.25.12': - resolution: {integrity: sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==} - engines: {node: '>=18'} - cpu: [arm64] - os: [win32] - - '@esbuild/win32-ia32@0.25.12': - resolution: {integrity: sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==} - engines: {node: '>=18'} - cpu: [ia32] - os: [win32] - - '@esbuild/win32-x64@0.25.12': - resolution: {integrity: sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==} - engines: {node: '>=18'} - cpu: [x64] - os: [win32] + '@emnapi/wasi-threads@1.2.1': + resolution: {integrity: sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==} '@eslint-community/eslint-utils@4.9.1': resolution: {integrity: sha512-phrYmNiYppR7znFEdqgfWHXR6NCkZEK7hwWDHZUjit/2/U0r6XvkDl0SYnoM51Hq7FhCGdLDT6zxCCOY1hexsQ==} @@ -1269,6 +1140,12 @@ packages: resolution: {integrity: sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==} engines: {node: '>=18.18'} + '@iconify-json/simple-icons@1.2.80': + resolution: {integrity: sha512-iglncJJ6X/dVuzFDU32MrHwwo4RBwivGf108dgyYg+HKS78ifx0h7sTenpDZMVT+UhdS6CSgZcvY/SvRXlIEUg==} + + '@iconify/types@2.0.0': + resolution: {integrity: sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg==} + '@inquirer/external-editor@1.0.3': resolution: {integrity: sha512-RWbSrDiYmO4LbejWY7ttpxczuwQyZLBUyygsA9Nsv95hpzUWwnNTVQmAq3xuh7vNwCp07UTmE5i11XAEExx4RA==} engines: {node: '>=18'} @@ -1318,6 +1195,12 @@ packages: resolution: {integrity: sha512-2+BzZbjRO7Ct61k8fMNHEtoKjeWI9pIlHFTqBwZ5icHpqszIgEZbjb1MW5Z0+bITTCTl3gk4PDBxs9tA/csXvA==} engines: {node: '>=18'} + '@napi-rs/wasm-runtime@1.1.4': + resolution: {integrity: sha512-3NQNNgA1YSlJb/kMH1ildASP9HW7/7kYnRI2szWJaofaS1hWmbGI4H+d3+22aGzXXN9IJ+n+GiFVcGipJP18ow==} + peerDependencies: + '@emnapi/core': ^1.7.1 + '@emnapi/runtime': ^1.7.1 + '@nodelib/fs.scandir@2.1.5': resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==} engines: {node: '>= 8'} @@ -1339,6 +1222,9 @@ packages: '@open-draft/until@2.1.0': resolution: {integrity: sha512-U69T3ItWHvLwGg5eJ0n3I62nWuE6ilHlmz7zM0npLBRvPRd7e6NYmg54vvRtP5mZG7kZqZCFVdsTWo7BPtBujg==} + '@oxc-project/types@0.127.0': + resolution: {integrity: sha512-aIYXQBo4lCbO4z0R3FHeucQHpF46l2LbMdxRvqvuRuW2OxdnSkcng5B8+K12spgLDj93rtN3+J2Vac/TIO+ciQ==} + '@pnpm/config.env-replace@1.1.0': resolution: {integrity: sha512-htyl8TWnKL7K/ESFa1oW2UB5lVDxuF5DpM7tBi6Hu2LNL3mWkIzNLG6N4zoCUP1lCKNxWy/3iu8mS8MvToGd6w==} engines: {node: '>=12.22.0'} @@ -1358,164 +1244,171 @@ packages: '@preconstruct/hook@0.4.0': resolution: {integrity: sha512-a7mrlPTM3tAFJyz43qb4pPVpUx8j8TzZBFsNFqcKcE/sEakNXRlQAuCT4RGZRf9dQiiUnBahzSIWawU4rENl+Q==} - '@rollup/plugin-alias@3.1.9': - resolution: {integrity: sha512-QI5fsEvm9bDzt32k39wpOwZhVzRcL5ydcffUHMyLVaVaLeC70I8TJZ17F1z1eMoLu4E/UOcH9BWVkKpIKdrfiw==} - engines: {node: '>=8.0.0'} - peerDependencies: - rollup: ^1.20.0||^2.0.0 - - '@rollup/plugin-commonjs@15.1.0': - resolution: {integrity: sha512-xCQqz4z/o0h2syQ7d9LskIMvBSH4PX5PjYdpSSvgS+pQik3WahkQVNWg3D8XJeYjZoVWnIUQYDghuEMRGrmQYQ==} - engines: {node: '>= 8.0.0'} - peerDependencies: - rollup: ^2.22.0 - - '@rollup/plugin-json@4.1.0': - resolution: {integrity: sha512-yfLbTdNS6amI/2OpmbiBoW12vngr5NW2jCJVZSBEz+H5KfUJZ2M7sDjk0U6GOOdCWFVScShte29o9NezJ53TPw==} - peerDependencies: - rollup: ^1.20.0 || ^2.0.0 - - '@rollup/plugin-node-resolve@11.2.1': - resolution: {integrity: sha512-yc2n43jcqVyGE2sqV5/YCmocy9ArjVAP/BeXyTtADTBBX6V0e5UMqwO8CdQ0kzjb6zu5P1qMzsScCMRvE9OlVg==} - engines: {node: '>= 10.0.0'} - peerDependencies: - rollup: ^1.20.0||^2.0.0 - - '@rollup/plugin-replace@2.4.2': - resolution: {integrity: sha512-IGcu+cydlUMZ5En85jxHH4qj2hta/11BHq95iHEyb2sbgiN0eCdzvUcHw5gt9pBL5lTi4JDYJ1acCoMGpTvEZg==} - peerDependencies: - rollup: ^1.20.0 || ^2.0.0 - - '@rollup/pluginutils@3.1.0': - resolution: {integrity: sha512-GksZ6pr6TpIjHm8h9lSQ8pi8BE9VeubNT0OMJ3B5uZJ8pz73NPiqOtCog/x2/QzM1ENChPKxMDhiQuRHsqc+lg==} - engines: {node: '>= 8.0.0'} - peerDependencies: - rollup: ^1.20.0||^2.0.0 - - '@rollup/rollup-android-arm-eabi@4.53.3': - resolution: {integrity: sha512-mRSi+4cBjrRLoaal2PnqH82Wqyb+d3HsPUN/W+WslCXsZsyHa9ZeQQX/pQsZaVIWDkPcpV6jJ+3KLbTbgnwv8w==} - cpu: [arm] - os: [android] - - '@rollup/rollup-android-arm64@4.53.3': - resolution: {integrity: sha512-CbDGaMpdE9sh7sCmTrTUyllhrg65t6SwhjlMJsLr+J8YjFuPmCEjbBSx4Z/e4SmDyH3aB5hGaJUP2ltV/vcs4w==} + '@rolldown/binding-android-arm64@1.0.0-rc.17': + resolution: {integrity: sha512-s70pVGhw4zqGeFnXWvAzJDlvxhlRollagdCCKRgOsgUOH3N1l0LIxf83AtGzmb5SiVM4Hjl5HyarMRfdfj3DaQ==} + engines: {node: ^20.19.0 || >=22.12.0} cpu: [arm64] os: [android] - '@rollup/rollup-darwin-arm64@4.53.3': - resolution: {integrity: sha512-Nr7SlQeqIBpOV6BHHGZgYBuSdanCXuw09hon14MGOLGmXAFYjx1wNvquVPmpZnl0tLjg25dEdr4IQ6GgyToCUA==} + '@rolldown/binding-darwin-arm64@1.0.0-rc.17': + resolution: {integrity: sha512-4ksWc9n0mhlZpZ9PMZgTGjeOPRu8MB1Z3Tz0Mo02eWfWCHMW1zN82Qz/pL/rC+yQa+8ZnutMF0JjJe7PjwasYw==} + engines: {node: ^20.19.0 || >=22.12.0} cpu: [arm64] os: [darwin] - '@rollup/rollup-darwin-x64@4.53.3': - resolution: {integrity: sha512-DZ8N4CSNfl965CmPktJ8oBnfYr3F8dTTNBQkRlffnUarJ2ohudQD17sZBa097J8xhQ26AwhHJ5mvUyQW8ddTsQ==} + '@rolldown/binding-darwin-x64@1.0.0-rc.17': + resolution: {integrity: sha512-SUSDOI6WwUVNcWxd02QEBjLdY1VPHvlEkw6T/8nYG322iYWCTxRb1vzk4E+mWWYehTp7ERibq54LSJGjmouOsw==} + engines: {node: ^20.19.0 || >=22.12.0} cpu: [x64] os: [darwin] - '@rollup/rollup-freebsd-arm64@4.53.3': - resolution: {integrity: sha512-yMTrCrK92aGyi7GuDNtGn2sNW+Gdb4vErx4t3Gv/Tr+1zRb8ax4z8GWVRfr3Jw8zJWvpGHNpss3vVlbF58DZ4w==} - cpu: [arm64] - os: [freebsd] - - '@rollup/rollup-freebsd-x64@4.53.3': - resolution: {integrity: sha512-lMfF8X7QhdQzseM6XaX0vbno2m3hlyZFhwcndRMw8fbAGUGL3WFMBdK0hbUBIUYcEcMhVLr1SIamDeuLBnXS+Q==} + '@rolldown/binding-freebsd-x64@1.0.0-rc.17': + resolution: {integrity: sha512-hwnz3nw9dbJ05EDO/PvcjaaewqqDy7Y1rn1UO81l8iIK1GjenME75dl16ajbvSSMfv66WXSRCYKIqfgq2KCfxw==} + engines: {node: ^20.19.0 || >=22.12.0} cpu: [x64] os: [freebsd] - '@rollup/rollup-linux-arm-gnueabihf@4.53.3': - resolution: {integrity: sha512-k9oD15soC/Ln6d2Wv/JOFPzZXIAIFLp6B+i14KhxAfnq76ajt0EhYc5YPeX6W1xJkAdItcVT+JhKl1QZh44/qw==} - cpu: [arm] - os: [linux] - libc: [glibc] - - '@rollup/rollup-linux-arm-musleabihf@4.53.3': - resolution: {integrity: sha512-vTNlKq+N6CK/8UktsrFuc+/7NlEYVxgaEgRXVUVK258Z5ymho29skzW1sutgYjqNnquGwVUObAaxae8rZ6YMhg==} + '@rolldown/binding-linux-arm-gnueabihf@1.0.0-rc.17': + resolution: {integrity: sha512-IS+W7epTcwANmFSQFrS1SivEXHtl1JtuQA9wlxrZTcNi6mx+FDOYrakGevvvTwgj2JvWiK8B29/qD9BELZPyXQ==} + engines: {node: ^20.19.0 || >=22.12.0} cpu: [arm] os: [linux] - libc: [musl] - '@rollup/rollup-linux-arm64-gnu@4.53.3': - resolution: {integrity: sha512-RGrFLWgMhSxRs/EWJMIFM1O5Mzuz3Xy3/mnxJp/5cVhZ2XoCAxJnmNsEyeMJtpK+wu0FJFWz+QF4mjCA7AUQ3w==} + '@rolldown/binding-linux-arm64-gnu@1.0.0-rc.17': + resolution: {integrity: sha512-e6usGaHKW5BMNZOymS1UcEYGowQMWcgZ71Z17Sl/h2+ZziNJ1a9n3Zvcz6LdRyIW5572wBCTH/Z+bKuZouGk9Q==} + engines: {node: ^20.19.0 || >=22.12.0} cpu: [arm64] os: [linux] libc: [glibc] - '@rollup/rollup-linux-arm64-musl@4.53.3': - resolution: {integrity: sha512-kASyvfBEWYPEwe0Qv4nfu6pNkITLTb32p4yTgzFCocHnJLAHs+9LjUu9ONIhvfT/5lv4YS5muBHyuV84epBo/A==} + '@rolldown/binding-linux-arm64-musl@1.0.0-rc.17': + resolution: {integrity: sha512-b/CgbwAJpmrRLp02RPfhbudf5tZnN9nsPWK82znefso832etkem8H7FSZwxrOI9djcdTP7U6YfNhbRnh7djErg==} + engines: {node: ^20.19.0 || >=22.12.0} cpu: [arm64] os: [linux] libc: [musl] - '@rollup/rollup-linux-loong64-gnu@4.53.3': - resolution: {integrity: sha512-JiuKcp2teLJwQ7vkJ95EwESWkNRFJD7TQgYmCnrPtlu50b4XvT5MOmurWNrCj3IFdyjBQ5p9vnrX4JM6I8OE7g==} - cpu: [loong64] - os: [linux] - libc: [glibc] - - '@rollup/rollup-linux-ppc64-gnu@4.53.3': - resolution: {integrity: sha512-EoGSa8nd6d3T7zLuqdojxC20oBfNT8nexBbB/rkxgKj5T5vhpAQKKnD+h3UkoMuTyXkP5jTjK/ccNRmQrPNDuw==} + '@rolldown/binding-linux-ppc64-gnu@1.0.0-rc.17': + resolution: {integrity: sha512-4EII1iNGRUN5WwGbF/kOh/EIkoDN9HsupgLQoXfY+D1oyJm7/F4t5PYU5n8SWZgG0FEwakyM8pGgwcBYruGTlA==} + engines: {node: ^20.19.0 || >=22.12.0} cpu: [ppc64] os: [linux] libc: [glibc] - '@rollup/rollup-linux-riscv64-gnu@4.53.3': - resolution: {integrity: sha512-4s+Wped2IHXHPnAEbIB0YWBv7SDohqxobiiPA1FIWZpX+w9o2i4LezzH/NkFUl8LRci/8udci6cLq+jJQlh+0g==} - cpu: [riscv64] - os: [linux] - libc: [glibc] - - '@rollup/rollup-linux-riscv64-musl@4.53.3': - resolution: {integrity: sha512-68k2g7+0vs2u9CxDt5ktXTngsxOQkSEV/xBbwlqYcUrAVh6P9EgMZvFsnHy4SEiUl46Xf0IObWVbMvPrr2gw8A==} - cpu: [riscv64] - os: [linux] - libc: [musl] - - '@rollup/rollup-linux-s390x-gnu@4.53.3': - resolution: {integrity: sha512-VYsFMpULAz87ZW6BVYw3I6sWesGpsP9OPcyKe8ofdg9LHxSbRMd7zrVrr5xi/3kMZtpWL/wC+UIJWJYVX5uTKg==} + '@rolldown/binding-linux-s390x-gnu@1.0.0-rc.17': + resolution: {integrity: sha512-AH8oq3XqQo4IibpVXvPeLDI5pzkpYn0WiZAfT05kFzoJ6tQNzwRdDYQ45M8I/gslbodRZwW8uxLhbSBbkv96rA==} + engines: {node: ^20.19.0 || >=22.12.0} cpu: [s390x] os: [linux] libc: [glibc] - '@rollup/rollup-linux-x64-gnu@4.53.3': - resolution: {integrity: sha512-3EhFi1FU6YL8HTUJZ51imGJWEX//ajQPfqWLI3BQq4TlvHy4X0MOr5q3D2Zof/ka0d5FNdPwZXm3Yyib/UEd+w==} + '@rolldown/binding-linux-x64-gnu@1.0.0-rc.17': + resolution: {integrity: sha512-cLnjV3xfo7KslbU41Z7z8BH/E1y5mzUYzAqih1d1MDaIGZRCMqTijqLv76/P7fyHuvUcfGsIpqCdddbxLLK9rA==} + engines: {node: ^20.19.0 || >=22.12.0} cpu: [x64] os: [linux] libc: [glibc] - '@rollup/rollup-linux-x64-musl@4.53.3': - resolution: {integrity: sha512-eoROhjcc6HbZCJr+tvVT8X4fW3/5g/WkGvvmwz/88sDtSJzO7r/blvoBDgISDiCjDRZmHpwud7h+6Q9JxFwq1Q==} + '@rolldown/binding-linux-x64-musl@1.0.0-rc.17': + resolution: {integrity: sha512-0phclDw1spsL7dUB37sIARuis2tAgomCJXAHZlpt8PXZ4Ba0dRP1e+66lsRqrfhISeN9bEGNjQs+T/Fbd7oYGw==} + engines: {node: ^20.19.0 || >=22.12.0} cpu: [x64] os: [linux] libc: [musl] - '@rollup/rollup-openharmony-arm64@4.53.3': - resolution: {integrity: sha512-OueLAWgrNSPGAdUdIjSWXw+u/02BRTcnfw9PN41D2vq/JSEPnJnVuBgw18VkN8wcd4fjUs+jFHVM4t9+kBSNLw==} + '@rolldown/binding-openharmony-arm64@1.0.0-rc.17': + resolution: {integrity: sha512-0ag/hEgXOwgw4t8QyQvUCxvEg+V0KBcA6YuOx9g0r02MprutRF5dyljgm3EmR02O292UX7UeS6HzWHAl6KgyhA==} + engines: {node: ^20.19.0 || >=22.12.0} cpu: [arm64] os: [openharmony] - '@rollup/rollup-win32-arm64-msvc@4.53.3': - resolution: {integrity: sha512-GOFuKpsxR/whszbF/bzydebLiXIHSgsEUp6M0JI8dWvi+fFa1TD6YQa4aSZHtpmh2/uAlj/Dy+nmby3TJ3pkTw==} - cpu: [arm64] - os: [win32] + '@rolldown/binding-wasm32-wasi@1.0.0-rc.17': + resolution: {integrity: sha512-LEXei6vo0E5wTGwpkJ4KoT3OZJRnglwldt5ziLzOlc6qqb55z4tWNq2A+PFqCJuvWWdP53CVhG1Z9NtToDPJrA==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [wasm32] - '@rollup/rollup-win32-ia32-msvc@4.53.3': - resolution: {integrity: sha512-iah+THLcBJdpfZ1TstDFbKNznlzoxa8fmnFYK4V67HvmuNYkVdAywJSoteUszvBQ9/HqN2+9AZghbajMsFT+oA==} - cpu: [ia32] + '@rolldown/binding-win32-arm64-msvc@1.0.0-rc.17': + resolution: {integrity: sha512-gUmyzBl3SPMa6hrqFUth9sVfcLBlYsbMzBx5PlexMroZStgzGqlZ26pYG89rBb45Mnia+oil6YAIFeEWGWhoZA==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [arm64] os: [win32] - '@rollup/rollup-win32-x64-gnu@4.53.3': - resolution: {integrity: sha512-J9QDiOIZlZLdcot5NXEepDkstocktoVjkaKUtqzgzpt2yWjGlbYiKyp05rWwk4nypbYUNoFAztEgixoLaSETkg==} + '@rolldown/binding-win32-x64-msvc@1.0.0-rc.17': + resolution: {integrity: sha512-3hkiolcUAvPB9FLb3UZdfjVVNWherN1f/skkGWJP/fgSQhYUZpSIRr0/I8ZK9TkF3F7kxvJAk0+IcKvPHk9qQg==} + engines: {node: ^20.19.0 || >=22.12.0} cpu: [x64] os: [win32] - '@rollup/rollup-win32-x64-msvc@4.53.3': - resolution: {integrity: sha512-UhTd8u31dXadv0MopwGgNOBpUVROFKWVQgAg5N1ESyCz8AuBcMqm4AuTjrwgQKGDfoFuz02EuMRHQIw/frmYKQ==} - cpu: [x64] - os: [win32] + '@rolldown/pluginutils@1.0.0-rc.13': + resolution: {integrity: sha512-3ngTAv6F/Py35BsYbeeLeecvhMKdsKm4AoOETVhAA+Qc8nrA2I0kF7oa93mE9qnIurngOSpMnQ0x2nQY2FPviA==} + + '@rolldown/pluginutils@1.0.0-rc.17': + resolution: {integrity: sha512-n8iosDOt6Ig1UhJ2AYqoIhHWh/isz0xpicHTzpKBeotdVsTEcxsSA/i3EVM7gQAj0rU27OLAxCjzlj15IWY7bg==} + + '@rollup/plugin-alias@3.1.9': + resolution: {integrity: sha512-QI5fsEvm9bDzt32k39wpOwZhVzRcL5ydcffUHMyLVaVaLeC70I8TJZ17F1z1eMoLu4E/UOcH9BWVkKpIKdrfiw==} + engines: {node: '>=8.0.0'} + peerDependencies: + rollup: ^1.20.0||^2.0.0 + + '@rollup/plugin-commonjs@15.1.0': + resolution: {integrity: sha512-xCQqz4z/o0h2syQ7d9LskIMvBSH4PX5PjYdpSSvgS+pQik3WahkQVNWg3D8XJeYjZoVWnIUQYDghuEMRGrmQYQ==} + engines: {node: '>= 8.0.0'} + peerDependencies: + rollup: ^2.22.0 + + '@rollup/plugin-json@4.1.0': + resolution: {integrity: sha512-yfLbTdNS6amI/2OpmbiBoW12vngr5NW2jCJVZSBEz+H5KfUJZ2M7sDjk0U6GOOdCWFVScShte29o9NezJ53TPw==} + peerDependencies: + rollup: ^1.20.0 || ^2.0.0 + + '@rollup/plugin-node-resolve@11.2.1': + resolution: {integrity: sha512-yc2n43jcqVyGE2sqV5/YCmocy9ArjVAP/BeXyTtADTBBX6V0e5UMqwO8CdQ0kzjb6zu5P1qMzsScCMRvE9OlVg==} + engines: {node: '>= 10.0.0'} + peerDependencies: + rollup: ^1.20.0||^2.0.0 + + '@rollup/plugin-replace@2.4.2': + resolution: {integrity: sha512-IGcu+cydlUMZ5En85jxHH4qj2hta/11BHq95iHEyb2sbgiN0eCdzvUcHw5gt9pBL5lTi4JDYJ1acCoMGpTvEZg==} + peerDependencies: + rollup: ^1.20.0 || ^2.0.0 + + '@rollup/pluginutils@3.1.0': + resolution: {integrity: sha512-GksZ6pr6TpIjHm8h9lSQ8pi8BE9VeubNT0OMJ3B5uZJ8pz73NPiqOtCog/x2/QzM1ENChPKxMDhiQuRHsqc+lg==} + engines: {node: '>= 8.0.0'} + peerDependencies: + rollup: ^1.20.0||^2.0.0 + + '@shikijs/core@3.23.0': + resolution: {integrity: sha512-NSWQz0riNb67xthdm5br6lAkvpDJRTgB36fxlo37ZzM2yq0PQFFzbd8psqC2XMPgCzo1fW6cVi18+ArJ44wqgA==} + + '@shikijs/engine-javascript@3.23.0': + resolution: {integrity: sha512-aHt9eiGFobmWR5uqJUViySI1bHMqrAgamWE1TYSUoftkAeCCAiGawPMwM+VCadylQtF4V3VNOZ5LmfItH5f3yA==} + + '@shikijs/engine-oniguruma@3.23.0': + resolution: {integrity: sha512-1nWINwKXxKKLqPibT5f4pAFLej9oZzQTsby8942OTlsJzOBZ0MWKiwzMsd+jhzu8YPCHAswGnnN1YtQfirL35g==} + + '@shikijs/langs@3.23.0': + resolution: {integrity: sha512-2Ep4W3Re5aB1/62RSYQInK9mM3HsLeB91cHqznAJMuylqjzNVAVCMnNWRHFtcNHXsoNRayP9z1qj4Sq3nMqYXg==} + + '@shikijs/themes@3.23.0': + resolution: {integrity: sha512-5qySYa1ZgAT18HR/ypENL9cUSGOeI2x+4IvYJu4JgVJdizn6kG4ia5Q1jDEOi7gTbN4RbuYtmHh0W3eccOrjMA==} + + '@shikijs/transformers@3.23.0': + resolution: {integrity: sha512-F9msZVxdF+krQNSdQ4V+Ja5QemeAoTQ2jxt7nJCwhDsdF1JWS3KxIQXA3lQbyKwS3J61oHRUSv4jYWv3CkaKTQ==} + + '@shikijs/types@3.23.0': + resolution: {integrity: sha512-3JZ5HXOZfYjsYSk0yPwBrkupyYSLpAE26Qc0HLghhZNGTZg/SKxXIIgoxOpmmeQP0RRSDJTk1/vPfw9tbw+jSQ==} + + '@shikijs/vscode-textmate@10.0.2': + resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==} '@standard-schema/spec@1.1.0': resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==} + '@tybys/wasm-util@0.10.1': + resolution: {integrity: sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==} + '@types/chai@5.2.3': resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==} @@ -1534,15 +1427,27 @@ packages: '@types/estree@1.0.8': resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==} + '@types/hast@3.0.4': + resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==} + '@types/js-yaml@4.0.9': resolution: {integrity: sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==} '@types/json-schema@7.0.15': resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==} + '@types/linkify-it@5.0.0': + resolution: {integrity: sha512-sVDA58zAw4eWAffKOaQH5/5j3XeayukzDk+ewSsnv3p4yJEZHCCzMDiZM8e0OUrRvmpGZ85jf4yDHkHsgBNr9Q==} + + '@types/markdown-it@14.1.2': + resolution: {integrity: sha512-promo4eFwuiW+TfGxhi+0x3czqTYJkG8qB17ZUJiVF10Xm7NLVRSLUsfRTU/6h1e24VvRnXCx+hG7li58lkzog==} + '@types/mdast@4.0.4': resolution: {integrity: sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==} + '@types/mdurl@2.0.0': + resolution: {integrity: sha512-RGdgjQUZba5p6QEFAVx2OGb8rQDL/cPRG7GiedRzMcJ1tYnUANBncjbSB1NRGwbvjcPeikRABz2nshyPk1bhWg==} + '@types/ms@2.1.0': resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==} @@ -1561,6 +1466,9 @@ packages: '@types/unist@3.0.3': resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==} + '@types/web-bluetooth@0.0.21': + resolution: {integrity: sha512-oIQLCGWtcFZy2JW77j9k8nHzAOpqMHLQejDA48XXMWH6tjCQHz5RCFz1bzsmROyL6PUm+LLnUiI4BCn221inxA==} + '@typescript-eslint/eslint-plugin@8.59.1': resolution: {integrity: sha512-BOziFIfE+6osHO9FoJG4zjoHUcvI7fTNBSpdAwrNH0/TLvzjsk2oo8XSSOT2HhqUyhZPfHv4UOffoJ9oEEQ7Ag==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} @@ -1620,6 +1528,16 @@ packages: resolution: {integrity: sha512-LdDNl6C5iJExcM0Yh0PwAIBb9PrSiCsWamF/JyEZawm3kFDnRoaq3LGE4bpyRao/fWeGKKyw7icx0YxrLFC5Cg==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} + '@ungap/structured-clone@1.3.0': + resolution: {integrity: sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==} + + '@vitejs/plugin-vue@6.0.6': + resolution: {integrity: sha512-u9HHgfrq3AjXlysn0eINFnWQOJQLO9WN6VprZ8FXl7A2bYisv3Hui9Ij+7QZ41F/WYWarHjwBbXtD7dKg3uxbg==} + engines: {node: ^20.19.0 || >=22.12.0} + peerDependencies: + vite: ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0 + vue: ^3.2.25 + '@vitest/coverage-v8@4.1.5': resolution: {integrity: sha512-38C0/Ddb7HcRG0Z4/DUem8x57d2p9jYgp18mkaYswEOQBGsI1CG4f/hjm0ZCeaJfWhSZ4k7jgs29V1Zom7Ki9A==} peerDependencies: @@ -1674,6 +1592,99 @@ packages: '@vitest/utils@4.1.5': resolution: {integrity: sha512-76wdkrmfXfqGjueGgnb45ITPyUi1ycZ4IHgC2bhPDUfWHklY/q3MdLOAB+TF1e6xfl8NxNY0ZYaPCFNWSsw3Ug==} + '@vue/compiler-core@3.5.33': + resolution: {integrity: sha512-3PZLQwFw4Za3TC8t0FvTy3wI16Kt+pmwcgNZca4Pj9iWL2E72a/gZlpBtAJvEdDMdCxdG/qq0C7PN0bsJuv0Rw==} + + '@vue/compiler-dom@3.5.33': + resolution: {integrity: sha512-PXq0yrfCLzzL07rbXO4awtXY1Z06LG2eu6Adg3RJFa/j3Cii217XxxLXG22N330gw7GmALCY0Z8RgXEviwgpjA==} + + '@vue/compiler-sfc@3.5.33': + resolution: {integrity: sha512-UTUvRO9cY+rROrx/pvN9P5Z7FgA6QGfokUCfhQE4EnmUj3rVnK+CHI0LsEO1pg+I7//iRYMUfcNcCPe7tg0CoA==} + + '@vue/compiler-ssr@3.5.33': + resolution: {integrity: sha512-IErjYdnj1qIupG5xxiVIYiiRvDhGWV4zuh/RCrwfYpuL+HWQzeU6lCk/nF9r7olWMnjKxCAkOctT2qFWFkzb1A==} + + '@vue/devtools-api@8.1.1': + resolution: {integrity: sha512-bsDMJ07b3GN1puVwJb/fyFnj/U2imyswK5UQVLZwVl7O05jDrt6BHxeG5XffmOOdasOj/bOmIjxJvGPxU7pcqw==} + + '@vue/devtools-kit@8.1.1': + resolution: {integrity: sha512-gVBaBv++i+adg4JpH71k9ppl4soyR7Y2McEqO5YNgv0BI1kMZ7BDX5gnwkZ5COYgiCyhejZG+yGNrBAjj6Coqg==} + + '@vue/devtools-shared@8.1.1': + resolution: {integrity: sha512-+h4ttmJYl/txpxHKaoZcaKpC+pvckgLzIDiSQlaQ7kKthKh8KuwoLW2D8hPJEnqKzXOvu15UHEoGyngAXCz0EQ==} + + '@vue/reactivity@3.5.33': + resolution: {integrity: sha512-p8UfIqyIhb0rYGlSgSBV+lPhF2iUSBcRy7enhTmPqKWadHy9kcOFYF1AejYBP9P+avnd3OBbD49DU4pLWX/94A==} + + '@vue/runtime-core@3.5.33': + resolution: {integrity: sha512-UpFF45RI9//a7rvq7RdOQblb4tup7hHG9QsmIrxkFQLzQ7R8/iNQ5LE15NhLZ1/WcHMU2b47u6P33CPUelHyIQ==} + + '@vue/runtime-dom@3.5.33': + resolution: {integrity: sha512-IOxMsAOwquhfITgmOgaPYl7/j8gKUxUFoflRc+u4LxyD3+783xne8vNta1PONVCvCV9A0w7hkyEepINDqfO0tw==} + + '@vue/server-renderer@3.5.33': + resolution: {integrity: sha512-0xylq/8/h44lVG0pZFknv1XIdEgymq2E9n59uTWJBG+dIgiT0TMCSsxrN7nO16Z0MU0MPjFcguBbZV8Itk52Hw==} + peerDependencies: + vue: 3.5.33 + + '@vue/shared@3.5.33': + resolution: {integrity: sha512-5vR2QIlmaLG77Ygd4pMP6+SGQ5yox9VhtnbDWTy9DzMzdmeLxZ1QqxrywEZ9sa1AVubfIJyaCG3ytyWU81ufcQ==} + + '@vueuse/core@14.3.0': + resolution: {integrity: sha512-aHfz47g0ZhMtTVHmIzMVpJy8ePhhOy68GY5bv110+5DVtZ+W7BsOx+m61UNQqfrWyPztIHIanWa3E2tib3NFIw==} + peerDependencies: + vue: ^3.5.0 + + '@vueuse/integrations@14.3.0': + resolution: {integrity: sha512-76I5FT2ESvCmCaSwapI+a/u/CFtNXmzl9f9lNp1hRtx8vKB8hfiokJr8IvQqcQG5ckGXElyXK516b54ozV3MvA==} + peerDependencies: + async-validator: ^4 + axios: ^1 + change-case: ^5 + drauu: ^0.4 + focus-trap: ^7 || ^8 + fuse.js: ^7 + idb-keyval: ^6 + jwt-decode: ^4 + nprogress: ^0.2 + qrcode: ^1.5 + sortablejs: ^1 + universal-cookie: ^7 || ^8 + vue: ^3.5.0 + peerDependenciesMeta: + async-validator: + optional: true + axios: + optional: true + change-case: + optional: true + drauu: + optional: true + focus-trap: + optional: true + fuse.js: + optional: true + idb-keyval: + optional: true + jwt-decode: + optional: true + nprogress: + optional: true + qrcode: + optional: true + sortablejs: + optional: true + universal-cookie: + optional: true + + '@vueuse/metadata@14.3.0': + resolution: {integrity: sha512-BwxmbAzwAVF50+MW57GXOUEV61nFBGnlBvrTqj49PqWJu3uw7hdu72ztXeZ33RdZtDY6kO+bfCAE1PCn88Tktw==} + + '@vueuse/shared@14.3.0': + resolution: {integrity: sha512-bZpge9eSXwa4ToSiqJ7j6KRwhAsneMFoSz3LMWKQDkqimm3D/tbFlrklrs/IOqC8tEcYmXQZJ6N0UrjhBirVCg==} + peerDependencies: + vue: ^3.5.0 + acorn-jsx@5.3.2: resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==} peerDependencies: @@ -1739,6 +1750,9 @@ packages: resolution: {integrity: sha512-D5vIoztZOq1XM54LUdttJVc96ggEsIfju2JBvht06pSzpckp3C7HReun67Bghzrtdsq9XdMGbSSB3v3GhMNmAA==} hasBin: true + birpc@2.9.0: + resolution: {integrity: sha512-KrayHS5pBi69Xi9JmvoqrIgYGDkD6mcSe/i6YKi3w5kekCLzrX4+nawcXqrj2tIp50Kw/mT/s3p+GVK0A0sKxw==} + brace-expansion@1.1.12: resolution: {integrity: sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==} @@ -1765,6 +1779,9 @@ packages: caniuse-lite@1.0.30001760: resolution: {integrity: sha512-7AAMPcueWELt1p3mi13HR/LHH0TJLT11cnwDJEs3xA4+CK/PLKeO9Kl1oru24htkyUKtkGCvAx4ohB0Ttry8Dw==} + ccount@2.0.1: + resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==} + chai@6.2.2: resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==} engines: {node: '>=18'} @@ -1773,6 +1790,12 @@ packages: resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==} engines: {node: '>=10'} + character-entities-html4@2.1.0: + resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==} + + character-entities-legacy@3.0.0: + resolution: {integrity: sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==} + character-entities@2.0.2: resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==} @@ -1790,6 +1813,9 @@ packages: color-name@1.1.4: resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==} + comma-separated-tokens@2.0.3: + resolution: {integrity: sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==} + commander@2.20.3: resolution: {integrity: sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==} @@ -1812,6 +1838,9 @@ packages: resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==} engines: {node: '>= 8'} + csstype@3.2.3: + resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==} + dataloader@1.4.0: resolution: {integrity: sha512-68s5jYdlvasItOJnCuI2Q9s4q98g0pCyL3HrcKJu8KNugUl8ahgmZYg38ysLTgQjjXX3H8CJLkAvWrclWfcalw==} @@ -1853,6 +1882,10 @@ packages: resolution: {integrity: sha512-y+8xyqdGLL+6sh0tVeHcfP/QDd8gUgbasolJJpY7NgeQGSZ739bDtSiaiDgtoicy+mtYB81dKLxO9xRhCyIB3A==} engines: {node: '>=12.20'} + detect-libc@2.1.2: + resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==} + engines: {node: '>=8'} + devlop@1.1.0: resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==} @@ -1871,17 +1904,16 @@ packages: resolution: {integrity: sha512-rRqJg/6gd538VHvR3PSrdRBb/1Vy2YfzHqzvbhGIQpDRKIa4FgV/54b5Q1xYSxOOwKvjXweS26E0Q+nAMwp2pQ==} engines: {node: '>=8.6'} + entities@7.0.1: + resolution: {integrity: sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==} + engines: {node: '>=0.12'} + error-ex@1.3.4: resolution: {integrity: sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ==} es-module-lexer@2.1.0: resolution: {integrity: sha512-n27zTYMjYu1aj4MjCWzSP7G9r75utsaoc8m61weK+W8JMBGGQybd43GstCXZ3WNmSFtGT9wi59qQTW6mhTR5LQ==} - esbuild@0.25.12: - resolution: {integrity: sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==} - engines: {node: '>=18'} - hasBin: true - escalade@3.2.0: resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==} engines: {node: '>=6'} @@ -2022,6 +2054,9 @@ packages: flatted@3.3.3: resolution: {integrity: sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==} + focus-trap@8.2.0: + resolution: {integrity: sha512-CaBdQ9P4fa/yCA6pDf/3aJd8bf9IOG5QGK21/E+86o2V4V8kzXaR4A9E6tNR7KkkS1+T5ZIU1tJDBDLwsucz9g==} + fs-extra@9.1.0: resolution: {integrity: sha512-hcg3ZmepS30/7BSFqRvoo3DOMQu7IjqxO5nCDt+zM9XWjb33Wg7ziNT+Qvqbuc3+gWpzO02JubVyk2G4Zvo1OQ==} engines: {node: '>=10'} @@ -2088,9 +2123,21 @@ packages: resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==} engines: {node: '>= 0.4'} + hast-util-to-html@9.0.5: + resolution: {integrity: sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==} + + hast-util-whitespace@3.0.0: + resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==} + + hookable@5.5.3: + resolution: {integrity: sha512-Yc+BQe8SvoXH1643Qez1zqLRmbA5rCL+sSmk6TVos0LWVfNIB7PGncdlId77WzLGSIB5KaWgTaNTs2lNVEI6VQ==} + html-escaper@2.0.2: resolution: {integrity: sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==} + html-void-elements@3.0.0: + resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==} + human-id@4.1.3: resolution: {integrity: sha512-tsYlhAYpjCKa//8rXZ9DqKEawhPoSytweBC2eNvcaDK+57RZLHGqNs3PZTQO6yekLFSuvA6AlnAfrw1uBvtb+Q==} hasBin: true @@ -2238,6 +2285,80 @@ packages: resolution: {integrity: sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==} engines: {node: '>= 0.8.0'} + lightningcss-android-arm64@1.32.0: + resolution: {integrity: sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==} + engines: {node: '>= 12.0.0'} + cpu: [arm64] + os: [android] + + lightningcss-darwin-arm64@1.32.0: + resolution: {integrity: sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==} + engines: {node: '>= 12.0.0'} + cpu: [arm64] + os: [darwin] + + lightningcss-darwin-x64@1.32.0: + resolution: {integrity: sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==} + engines: {node: '>= 12.0.0'} + cpu: [x64] + os: [darwin] + + lightningcss-freebsd-x64@1.32.0: + resolution: {integrity: sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==} + engines: {node: '>= 12.0.0'} + cpu: [x64] + os: [freebsd] + + lightningcss-linux-arm-gnueabihf@1.32.0: + resolution: {integrity: sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==} + engines: {node: '>= 12.0.0'} + cpu: [arm] + os: [linux] + + lightningcss-linux-arm64-gnu@1.32.0: + resolution: {integrity: sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==} + engines: {node: '>= 12.0.0'} + cpu: [arm64] + os: [linux] + libc: [glibc] + + lightningcss-linux-arm64-musl@1.32.0: + resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==} + engines: {node: '>= 12.0.0'} + cpu: [arm64] + os: [linux] + libc: [musl] + + lightningcss-linux-x64-gnu@1.32.0: + resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==} + engines: {node: '>= 12.0.0'} + cpu: [x64] + os: [linux] + libc: [glibc] + + lightningcss-linux-x64-musl@1.32.0: + resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==} + engines: {node: '>= 12.0.0'} + cpu: [x64] + os: [linux] + libc: [musl] + + lightningcss-win32-arm64-msvc@1.32.0: + resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==} + engines: {node: '>= 12.0.0'} + cpu: [arm64] + os: [win32] + + lightningcss-win32-x64-msvc@1.32.0: + resolution: {integrity: sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==} + engines: {node: '>= 12.0.0'} + cpu: [x64] + os: [win32] + + lightningcss@1.32.0: + resolution: {integrity: sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==} + engines: {node: '>= 12.0.0'} + lines-and-columns@1.2.4: resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==} @@ -2267,12 +2388,18 @@ packages: resolution: {integrity: sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==} engines: {node: '>=10'} + mark.js@8.11.1: + resolution: {integrity: sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==} + mdast-util-from-markdown@2.0.2: resolution: {integrity: sha512-uZhTV/8NBuw0WHkPTrCqDOl0zVe1BIng5ZtHoDk49ME1qqcjYmmLmOf0gELgcRMxN4w2iuIeVso5/6QymSrgmA==} mdast-util-phrasing@4.1.0: resolution: {integrity: sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==} + mdast-util-to-hast@13.2.1: + resolution: {integrity: sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==} + mdast-util-to-markdown@2.1.2: resolution: {integrity: sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==} @@ -2363,6 +2490,9 @@ packages: minimist@1.2.8: resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==} + minisearch@7.2.0: + resolution: {integrity: sha512-dqT2XBYUOZOiC5t2HRnwADjhNS2cecp9u+TJRiJ1Qp/f5qjkeT5APcGPjHw+bz89Ms8Jp+cG4AlE+QZ/QnDglg==} + mri@1.2.0: resolution: {integrity: sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==} engines: {node: '>=4'} @@ -2406,6 +2536,12 @@ packages: once@1.4.0: resolution: {integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==} + oniguruma-parser@0.12.2: + resolution: {integrity: sha512-6HVa5oIrgMC6aA6WF6XyyqbhRPJrKR02L20+2+zpDtO5QAzGHAUGw5TKQvwi5vctNnRHkJYmjAhRVQF2EKdTQw==} + + oniguruma-to-es@4.3.6: + resolution: {integrity: sha512-csuQ9x3Yr0cEIs/Zgx/OEt9iBw9vqIunAPQkx19R/fiMq2oGVTgcMqO/V3Ybqefr1TBvosI6jU539ksaBULJyA==} + optionator@0.9.4: resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==} engines: {node: '>= 0.8.0'} @@ -2466,6 +2602,9 @@ packages: pathe@2.0.3: resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==} + perfect-debounce@2.1.0: + resolution: {integrity: sha512-LjgdTytVFXeUgtHZr9WYViYSM/g8MkcTPYDlPa3cDqMirHjKiSZPYd6DoL7pK8AJQr+uWkQvCjHNdiMqsrJs+g==} + picocolors@1.1.1: resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==} @@ -2481,8 +2620,8 @@ packages: resolution: {integrity: sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==} engines: {node: '>= 6'} - postcss@8.5.6: - resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==} + postcss@8.5.13: + resolution: {integrity: sha512-qif0+jGGZoLWdHey3UFHHWP0H7Gbmsk8T5VEqyYFbWqPr1XqvLGBbk/sl8V5exGmcYJklJOhOQq1pV9IcsiFag==} engines: {node: ^10 || ^12 || >=14} prelude-ls@1.2.1: @@ -2498,6 +2637,9 @@ packages: resolution: {integrity: sha512-vGrhOavPSTz4QVNuBNdcNXePNdNMaO1xj9yBeH1ScQPjk/rhg9sSlCXPhMkFuaNNW/syTvYqsnbIJxMBfRbbag==} engines: {node: '>= 8'} + property-information@7.1.0: + resolution: {integrity: sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==} + proto-list@1.2.4: resolution: {integrity: sha512-vtK/94akxsTMhe0/cbfpR+syPuszcuwhqVjJq26CuNDgFGj682oRBXOP5MJpv2r7JtE8MsiepGIqvvOTBwn2vA==} @@ -2523,6 +2665,15 @@ packages: regenerate@1.4.2: resolution: {integrity: sha512-zrceR/XhGYU/d/opr2EKO7aRHUeiBI8qjtfHqADTwZd6Szfy16la6kqD0MIUs5z5hx6AaKa+PixpPrR289+I0A==} + regex-recursion@6.0.2: + resolution: {integrity: sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==} + + regex-utilities@2.3.0: + resolution: {integrity: sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==} + + regex@6.1.0: + resolution: {integrity: sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg==} + regexpu-core@6.4.0: resolution: {integrity: sha512-0ghuzq67LI9bLXpOX/ISfve/Mq33a4aFRzoQYhnnok1JOFpmE/A2TBGkNVenOGEeSBCjIiWcc6MVOG5HEQv0sA==} engines: {node: '>=4'} @@ -2558,16 +2709,16 @@ packages: resolution: {integrity: sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==} engines: {iojs: '>=1.0.0', node: '>=0.10.0'} + rolldown@1.0.0-rc.17: + resolution: {integrity: sha512-ZrT53oAKrtA4+YtBWPQbtPOxIbVDbxT0orcYERKd63VJTF13zPcgXTvD4843L8pcsI7M6MErt8QtON6lrB9tyA==} + engines: {node: ^20.19.0 || >=22.12.0} + hasBin: true + rollup@2.79.2: resolution: {integrity: sha512-fS6iqSPZDs3dr/y7Od6y5nha8dW1YnbgtsyotCVvoFGKbERG++CVRFv1meyGDE1SNItQA8BrnCw7ScdAhRJ3XQ==} engines: {node: '>=10.0.0'} hasBin: true - rollup@4.53.3: - resolution: {integrity: sha512-w8GmOxZfBmKknvdXU1sdM9NHcoQejwF/4mNgj2JuEEdRaHwwF12K7e9eXn1nLZ07ad+du76mkVsyeb2rKGllsA==} - engines: {node: '>=18.0.0', npm: '>=8.0.0'} - hasBin: true - run-parallel@1.2.0: resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==} @@ -2594,6 +2745,9 @@ packages: resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==} engines: {node: '>=8'} + shiki@3.23.0: + resolution: {integrity: sha512-55Dj73uq9ZXL5zyeRPzHQsK7Nbyt6Y10k5s7OjuFZGMhpp4r/rsLBH0o/0fstIzX1Lep9VxefWljK/SKCzygIA==} + siginfo@2.0.0: resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==} @@ -2616,6 +2770,9 @@ packages: resolution: {integrity: sha512-9NykojV5Uih4lgo5So5dtw+f0JgJX30KCNI8gwhz2J9A15wD0Ml6tjHKwf6fTSa6fAdVBdZeNOs9eJ71qCk8vA==} deprecated: Please use @jridgewell/sourcemap-codec instead + space-separated-tokens@2.0.2: + resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==} + stackback@0.0.2: resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==} @@ -2625,6 +2782,9 @@ packages: strict-event-emitter@0.5.1: resolution: {integrity: sha512-vMgjE/GGEPEFnhFub6pa4FmJBRBVOLpIII2hvCZ8Kzb7K0hlHo7mQv6xYrBvCL2LtAIBwFUK8wvuJgTVSQ5MFQ==} + stringify-entities@4.0.4: + resolution: {integrity: sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==} + strip-ansi@6.0.1: resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==} engines: {node: '>=8'} @@ -2641,6 +2801,9 @@ packages: resolution: {integrity: sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==} engines: {node: '>= 0.4'} + tabbable@6.4.0: + resolution: {integrity: sha512-05PUHKSNE8ou2dwIxTngl4EzcnsCDZGJ/iCLtDflR/SHB/ny14rXc+qU5P4mG9JkusiV7EivzY9Mhm55AzAvCg==} + tapable@2.3.3: resolution: {integrity: sha512-uxc/zpqFg6x7C8vOE7lh6Lbda8eEL9zmVm/PLeTPBRhh1xCgdWaQ+J1CUieGpIfm2HdtsUpRv+HshiasBMcc6A==} engines: {node: '>=6'} @@ -2661,6 +2824,10 @@ packages: resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==} engines: {node: '>=12.0.0'} + tinyglobby@0.2.16: + resolution: {integrity: sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==} + engines: {node: '>=12.0.0'} + tinyrainbow@3.1.0: resolution: {integrity: sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw==} engines: {node: '>=14.0.0'} @@ -2669,6 +2836,9 @@ packages: resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==} engines: {node: '>=8.0'} + trim-lines@3.0.1: + resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==} + ts-api-utils@2.5.0: resolution: {integrity: sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==} engines: {node: '>=18.12'} @@ -2680,6 +2850,9 @@ packages: peerDependencies: typescript: '>=4.0.0' + tslib@2.8.1: + resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==} + type-check@0.4.0: resolution: {integrity: sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==} engines: {node: '>= 0.8.0'} @@ -2718,6 +2891,9 @@ packages: unist-util-is@6.0.1: resolution: {integrity: sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==} + unist-util-position@5.0.0: + resolution: {integrity: sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==} + unist-util-stringify-position@4.0.0: resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==} @@ -2747,15 +2923,22 @@ packages: resolution: {integrity: sha512-IUoow1YUtvoBBC06dXs8bR8B9vuA3aJfmQNKMoaPG/OFsPmoQvw8xh+6Ye25Gx9DQhoEom3Pcu9MKHerm/NpUQ==} engines: {node: ^18.17.0 || >=20.5.0} - vite@7.2.7: - resolution: {integrity: sha512-ITcnkFeR3+fI8P1wMgItjGrR10170d8auB4EpMLPqmx6uxElH3a/hHGQabSHKdqd4FXWO1nFIp9rRn7JQ34ACQ==} + vfile-message@4.0.3: + resolution: {integrity: sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==} + + vfile@6.0.3: + resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==} + + vite@8.0.10: + resolution: {integrity: sha512-rZuUu9j6J5uotLDs+cAA4O5H4K1SfPliUlQwqa6YEwSrWDZzP4rhm00oJR5snMewjxF5V/K3D4kctsUTsIU9Mw==} engines: {node: ^20.19.0 || >=22.12.0} hasBin: true peerDependencies: '@types/node': ^20.19.0 || >=22.12.0 + '@vitejs/devtools': ^0.1.0 + esbuild: ^0.27.0 || ^0.28.0 jiti: '>=1.21.0' less: ^4.0.0 - lightningcss: ^1.21.0 sass: ^1.70.0 sass-embedded: ^1.70.0 stylus: '>=0.54.8' @@ -2766,12 +2949,14 @@ packages: peerDependenciesMeta: '@types/node': optional: true + '@vitejs/devtools': + optional: true + esbuild: + optional: true jiti: optional: true less: optional: true - lightningcss: - optional: true sass: optional: true sass-embedded: @@ -2787,6 +2972,21 @@ packages: yaml: optional: true + vitepress@2.0.0-alpha.17: + resolution: {integrity: sha512-Z3VPUpwk/bHYqt1uMVOOK1/4xFiWQov1GNc2FvMdz6kvje4JRXEOngVI9C+bi5jeedMSHiA4dwKkff1NCvbZ9Q==} + hasBin: true + peerDependencies: + markdown-it-mathjax3: ^4 + oxc-minify: '*' + postcss: ^8 + peerDependenciesMeta: + markdown-it-mathjax3: + optional: true + oxc-minify: + optional: true + postcss: + optional: true + vitest@4.1.5: resolution: {integrity: sha512-9Xx1v3/ih3m9hN+SbfkUyy0JAs72ap3r7joc87XL6jwF0jGg6mFBvQ1SrwaX+h8BlkX6Hz9shdd1uo6AF+ZGpg==} engines: {node: ^20.0.0 || ^22.0.0 || >=24.0.0} @@ -2828,6 +3028,14 @@ packages: jsdom: optional: true + vue@3.5.33: + resolution: {integrity: sha512-1AgChhx5w3ALgT4oK3acm2Es/7jyZhWSVUfs3rOBlGQC0rjEDkS7G4lWlJJGGNQD+BV3reCwbQrOe1mPNwKHBQ==} + peerDependencies: + typescript: '*' + peerDependenciesMeta: + typescript: + optional: true + which@2.0.2: resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==} engines: {node: '>= 8'} @@ -3535,99 +3743,43 @@ snapshots: '@babel/traverse@7.28.5': dependencies: - '@babel/code-frame': 7.27.1 - '@babel/generator': 7.28.5 - '@babel/helper-globals': 7.28.0 - '@babel/parser': 7.29.3 - '@babel/template': 7.27.2 - '@babel/types': 7.29.0 - debug: 4.4.3 - transitivePeerDependencies: - - supports-color - - '@babel/types@7.29.0': - dependencies: - '@babel/helper-string-parser': 7.27.1 - '@babel/helper-validator-identifier': 7.28.5 - - '@bcoe/v8-coverage@1.0.2': {} - - '@esbuild/aix-ppc64@0.25.12': - optional: true - - '@esbuild/android-arm64@0.25.12': - optional: true - - '@esbuild/android-arm@0.25.12': - optional: true - - '@esbuild/android-x64@0.25.12': - optional: true - - '@esbuild/darwin-arm64@0.25.12': - optional: true - - '@esbuild/darwin-x64@0.25.12': - optional: true - - '@esbuild/freebsd-arm64@0.25.12': - optional: true - - '@esbuild/freebsd-x64@0.25.12': - optional: true - - '@esbuild/linux-arm64@0.25.12': - optional: true - - '@esbuild/linux-arm@0.25.12': - optional: true - - '@esbuild/linux-ia32@0.25.12': - optional: true - - '@esbuild/linux-loong64@0.25.12': - optional: true - - '@esbuild/linux-mips64el@0.25.12': - optional: true - - '@esbuild/linux-ppc64@0.25.12': - optional: true - - '@esbuild/linux-riscv64@0.25.12': - optional: true - - '@esbuild/linux-s390x@0.25.12': - optional: true - - '@esbuild/linux-x64@0.25.12': - optional: true - - '@esbuild/netbsd-arm64@0.25.12': - optional: true + '@babel/code-frame': 7.27.1 + '@babel/generator': 7.28.5 + '@babel/helper-globals': 7.28.0 + '@babel/parser': 7.29.3 + '@babel/template': 7.27.2 + '@babel/types': 7.29.0 + debug: 4.4.3 + transitivePeerDependencies: + - supports-color - '@esbuild/netbsd-x64@0.25.12': - optional: true + '@babel/types@7.29.0': + dependencies: + '@babel/helper-string-parser': 7.27.1 + '@babel/helper-validator-identifier': 7.28.5 - '@esbuild/openbsd-arm64@0.25.12': - optional: true + '@bcoe/v8-coverage@1.0.2': {} - '@esbuild/openbsd-x64@0.25.12': - optional: true + '@docsearch/css@4.6.3': {} - '@esbuild/openharmony-arm64@0.25.12': - optional: true + '@docsearch/js@4.6.3': {} - '@esbuild/sunos-x64@0.25.12': - optional: true + '@docsearch/sidepanel-js@4.6.3': {} - '@esbuild/win32-arm64@0.25.12': + '@emnapi/core@1.10.0': + dependencies: + '@emnapi/wasi-threads': 1.2.1 + tslib: 2.8.1 optional: true - '@esbuild/win32-ia32@0.25.12': + '@emnapi/runtime@1.10.0': + dependencies: + tslib: 2.8.1 optional: true - '@esbuild/win32-x64@0.25.12': + '@emnapi/wasi-threads@1.2.1': + dependencies: + tslib: 2.8.1 optional: true '@eslint-community/eslint-utils@4.9.1(eslint@10.3.0)': @@ -3680,6 +3832,12 @@ snapshots: '@humanwhocodes/retry@0.4.3': {} + '@iconify-json/simple-icons@1.2.80': + dependencies: + '@iconify/types': 2.0.0 + + '@iconify/types@2.0.0': {} + '@inquirer/external-editor@1.0.3(@types/node@24.12.2)': dependencies: chardet: 2.1.1 @@ -3749,6 +3907,13 @@ snapshots: outvariant: 1.4.3 strict-event-emitter: 0.5.1 + '@napi-rs/wasm-runtime@1.1.4(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)': + dependencies: + '@emnapi/core': 1.10.0 + '@emnapi/runtime': 1.10.0 + '@tybys/wasm-util': 0.10.1 + optional: true + '@nodelib/fs.scandir@2.1.5': dependencies: '@nodelib/fs.stat': 2.0.5 @@ -3770,6 +3935,8 @@ snapshots: '@open-draft/until@2.1.0': {} + '@oxc-project/types@0.127.0': {} + '@pnpm/config.env-replace@1.1.0': {} '@pnpm/network.ca-file@1.0.2': @@ -3832,6 +3999,59 @@ snapshots: transitivePeerDependencies: - supports-color + '@rolldown/binding-android-arm64@1.0.0-rc.17': + optional: true + + '@rolldown/binding-darwin-arm64@1.0.0-rc.17': + optional: true + + '@rolldown/binding-darwin-x64@1.0.0-rc.17': + optional: true + + '@rolldown/binding-freebsd-x64@1.0.0-rc.17': + optional: true + + '@rolldown/binding-linux-arm-gnueabihf@1.0.0-rc.17': + optional: true + + '@rolldown/binding-linux-arm64-gnu@1.0.0-rc.17': + optional: true + + '@rolldown/binding-linux-arm64-musl@1.0.0-rc.17': + optional: true + + '@rolldown/binding-linux-ppc64-gnu@1.0.0-rc.17': + optional: true + + '@rolldown/binding-linux-s390x-gnu@1.0.0-rc.17': + optional: true + + '@rolldown/binding-linux-x64-gnu@1.0.0-rc.17': + optional: true + + '@rolldown/binding-linux-x64-musl@1.0.0-rc.17': + optional: true + + '@rolldown/binding-openharmony-arm64@1.0.0-rc.17': + optional: true + + '@rolldown/binding-wasm32-wasi@1.0.0-rc.17': + dependencies: + '@emnapi/core': 1.10.0 + '@emnapi/runtime': 1.10.0 + '@napi-rs/wasm-runtime': 1.1.4(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0) + optional: true + + '@rolldown/binding-win32-arm64-msvc@1.0.0-rc.17': + optional: true + + '@rolldown/binding-win32-x64-msvc@1.0.0-rc.17': + optional: true + + '@rolldown/pluginutils@1.0.0-rc.13': {} + + '@rolldown/pluginutils@1.0.0-rc.17': {} + '@rollup/plugin-alias@3.1.9(rollup@2.79.2)': dependencies: rollup: 2.79.2 @@ -3876,74 +4096,51 @@ snapshots: picomatch: 2.3.1 rollup: 2.79.2 - '@rollup/rollup-android-arm-eabi@4.53.3': - optional: true - - '@rollup/rollup-android-arm64@4.53.3': - optional: true - - '@rollup/rollup-darwin-arm64@4.53.3': - optional: true - - '@rollup/rollup-darwin-x64@4.53.3': - optional: true - - '@rollup/rollup-freebsd-arm64@4.53.3': - optional: true - - '@rollup/rollup-freebsd-x64@4.53.3': - optional: true - - '@rollup/rollup-linux-arm-gnueabihf@4.53.3': - optional: true - - '@rollup/rollup-linux-arm-musleabihf@4.53.3': - optional: true - - '@rollup/rollup-linux-arm64-gnu@4.53.3': - optional: true - - '@rollup/rollup-linux-arm64-musl@4.53.3': - optional: true - - '@rollup/rollup-linux-loong64-gnu@4.53.3': - optional: true - - '@rollup/rollup-linux-ppc64-gnu@4.53.3': - optional: true - - '@rollup/rollup-linux-riscv64-gnu@4.53.3': - optional: true + '@shikijs/core@3.23.0': + dependencies: + '@shikijs/types': 3.23.0 + '@shikijs/vscode-textmate': 10.0.2 + '@types/hast': 3.0.4 + hast-util-to-html: 9.0.5 - '@rollup/rollup-linux-riscv64-musl@4.53.3': - optional: true + '@shikijs/engine-javascript@3.23.0': + dependencies: + '@shikijs/types': 3.23.0 + '@shikijs/vscode-textmate': 10.0.2 + oniguruma-to-es: 4.3.6 - '@rollup/rollup-linux-s390x-gnu@4.53.3': - optional: true + '@shikijs/engine-oniguruma@3.23.0': + dependencies: + '@shikijs/types': 3.23.0 + '@shikijs/vscode-textmate': 10.0.2 - '@rollup/rollup-linux-x64-gnu@4.53.3': - optional: true + '@shikijs/langs@3.23.0': + dependencies: + '@shikijs/types': 3.23.0 - '@rollup/rollup-linux-x64-musl@4.53.3': - optional: true + '@shikijs/themes@3.23.0': + dependencies: + '@shikijs/types': 3.23.0 - '@rollup/rollup-openharmony-arm64@4.53.3': - optional: true + '@shikijs/transformers@3.23.0': + dependencies: + '@shikijs/core': 3.23.0 + '@shikijs/types': 3.23.0 - '@rollup/rollup-win32-arm64-msvc@4.53.3': - optional: true + '@shikijs/types@3.23.0': + dependencies: + '@shikijs/vscode-textmate': 10.0.2 + '@types/hast': 3.0.4 - '@rollup/rollup-win32-ia32-msvc@4.53.3': - optional: true + '@shikijs/vscode-textmate@10.0.2': {} - '@rollup/rollup-win32-x64-gnu@4.53.3': - optional: true + '@standard-schema/spec@1.1.0': {} - '@rollup/rollup-win32-x64-msvc@4.53.3': + '@tybys/wasm-util@0.10.1': + dependencies: + tslib: 2.8.1 optional: true - '@standard-schema/spec@1.1.0': {} - '@types/chai@5.2.3': dependencies: '@types/deep-eql': 4.0.2 @@ -3961,14 +4158,27 @@ snapshots: '@types/estree@1.0.8': {} + '@types/hast@3.0.4': + dependencies: + '@types/unist': 3.0.3 + '@types/js-yaml@4.0.9': {} '@types/json-schema@7.0.15': {} + '@types/linkify-it@5.0.0': {} + + '@types/markdown-it@14.1.2': + dependencies: + '@types/linkify-it': 5.0.0 + '@types/mdurl': 2.0.0 + '@types/mdast@4.0.4': dependencies: '@types/unist': 3.0.3 + '@types/mdurl@2.0.0': {} + '@types/ms@2.1.0': {} '@types/node@24.12.2': @@ -3985,6 +4195,8 @@ snapshots: '@types/unist@3.0.3': {} + '@types/web-bluetooth@0.0.21': {} + '@typescript-eslint/eslint-plugin@8.59.1(@typescript-eslint/parser@8.59.1)(eslint@10.3.0)(typescript@6.0.3)': dependencies: '@eslint-community/regexpp': 4.12.2 @@ -4076,6 +4288,14 @@ snapshots: '@typescript-eslint/types': 8.59.1 eslint-visitor-keys: 5.0.1 + '@ungap/structured-clone@1.3.0': {} + + '@vitejs/plugin-vue@6.0.6(vite@8.0.10)(vue@3.5.33)': + dependencies: + '@rolldown/pluginutils': 1.0.0-rc.13 + vite: 8.0.10(@types/node@24.12.2)(terser@5.44.1) + vue: 3.5.33(typescript@6.0.3) + '@vitest/coverage-v8@4.1.5(vitest@4.1.5)': dependencies: '@bcoe/v8-coverage': 1.0.2 @@ -4088,7 +4308,7 @@ snapshots: obug: 2.1.1 std-env: 4.1.0 tinyrainbow: 3.1.0 - vitest: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@7.2.7) + vitest: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@8.0.10) '@vitest/eslint-plugin@1.6.16(@typescript-eslint/eslint-plugin@8.59.1)(eslint@10.3.0)(typescript@6.0.3)(vitest@4.1.5)': dependencies: @@ -4098,7 +4318,7 @@ snapshots: optionalDependencies: '@typescript-eslint/eslint-plugin': 8.59.1(@typescript-eslint/parser@8.59.1)(eslint@10.3.0)(typescript@6.0.3) typescript: 6.0.3 - vitest: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@7.2.7) + vitest: 4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@8.0.10) transitivePeerDependencies: - supports-color @@ -4111,13 +4331,13 @@ snapshots: chai: 6.2.2 tinyrainbow: 3.1.0 - '@vitest/mocker@4.1.5(vite@7.2.7)': + '@vitest/mocker@4.1.5(vite@8.0.10)': dependencies: '@vitest/spy': 4.1.5 estree-walker: 3.0.3 magic-string: 0.30.21 optionalDependencies: - vite: 7.2.7(@types/node@24.12.2)(terser@5.44.1) + vite: 8.0.10(@types/node@24.12.2)(terser@5.44.1) '@vitest/pretty-format@4.1.5': dependencies: @@ -4143,6 +4363,94 @@ snapshots: convert-source-map: 2.0.0 tinyrainbow: 3.1.0 + '@vue/compiler-core@3.5.33': + dependencies: + '@babel/parser': 7.29.3 + '@vue/shared': 3.5.33 + entities: 7.0.1 + estree-walker: 2.0.2 + source-map-js: 1.2.1 + + '@vue/compiler-dom@3.5.33': + dependencies: + '@vue/compiler-core': 3.5.33 + '@vue/shared': 3.5.33 + + '@vue/compiler-sfc@3.5.33': + dependencies: + '@babel/parser': 7.29.3 + '@vue/compiler-core': 3.5.33 + '@vue/compiler-dom': 3.5.33 + '@vue/compiler-ssr': 3.5.33 + '@vue/shared': 3.5.33 + estree-walker: 2.0.2 + magic-string: 0.30.21 + postcss: 8.5.13 + source-map-js: 1.2.1 + + '@vue/compiler-ssr@3.5.33': + dependencies: + '@vue/compiler-dom': 3.5.33 + '@vue/shared': 3.5.33 + + '@vue/devtools-api@8.1.1': + dependencies: + '@vue/devtools-kit': 8.1.1 + + '@vue/devtools-kit@8.1.1': + dependencies: + '@vue/devtools-shared': 8.1.1 + birpc: 2.9.0 + hookable: 5.5.3 + perfect-debounce: 2.1.0 + + '@vue/devtools-shared@8.1.1': {} + + '@vue/reactivity@3.5.33': + dependencies: + '@vue/shared': 3.5.33 + + '@vue/runtime-core@3.5.33': + dependencies: + '@vue/reactivity': 3.5.33 + '@vue/shared': 3.5.33 + + '@vue/runtime-dom@3.5.33': + dependencies: + '@vue/reactivity': 3.5.33 + '@vue/runtime-core': 3.5.33 + '@vue/shared': 3.5.33 + csstype: 3.2.3 + + '@vue/server-renderer@3.5.33(vue@3.5.33)': + dependencies: + '@vue/compiler-ssr': 3.5.33 + '@vue/shared': 3.5.33 + vue: 3.5.33(typescript@6.0.3) + + '@vue/shared@3.5.33': {} + + '@vueuse/core@14.3.0(vue@3.5.33)': + dependencies: + '@types/web-bluetooth': 0.0.21 + '@vueuse/metadata': 14.3.0 + '@vueuse/shared': 14.3.0(vue@3.5.33) + vue: 3.5.33(typescript@6.0.3) + + '@vueuse/integrations@14.3.0(focus-trap@8.2.0)(vue@3.5.33)': + dependencies: + '@vueuse/core': 14.3.0(vue@3.5.33) + '@vueuse/shared': 14.3.0(vue@3.5.33) + vue: 3.5.33(typescript@6.0.3) + optionalDependencies: + focus-trap: 8.2.0 + + '@vueuse/metadata@14.3.0': {} + + '@vueuse/shared@14.3.0(vue@3.5.33)': + dependencies: + vue: 3.5.33(typescript@6.0.3) + acorn-jsx@5.3.2(acorn@8.16.0): dependencies: acorn: 8.16.0 @@ -4206,6 +4514,8 @@ snapshots: baseline-browser-mapping@2.9.5: {} + birpc@2.9.0: {} + brace-expansion@1.1.12: dependencies: balanced-match: 1.0.2 @@ -4233,6 +4543,8 @@ snapshots: caniuse-lite@1.0.30001760: {} + ccount@2.0.1: {} + chai@6.2.2: {} chalk@4.1.2: @@ -4240,6 +4552,10 @@ snapshots: ansi-styles: 4.3.0 supports-color: 7.2.0 + character-entities-html4@2.1.0: {} + + character-entities-legacy@3.0.0: {} + character-entities@2.0.2: {} chardet@2.1.1: {} @@ -4252,6 +4568,8 @@ snapshots: color-name@1.1.4: {} + comma-separated-tokens@2.0.3: {} + commander@2.20.3: {} commondir@1.0.1: {} @@ -4275,6 +4593,8 @@ snapshots: shebang-command: 2.0.0 which: 2.0.2 + csstype@3.2.3: {} + dataloader@1.4.0: {} dataloader@2.2.3: {} @@ -4299,6 +4619,8 @@ snapshots: detect-indent@7.0.2: {} + detect-libc@2.1.2: {} + devlop@1.1.0: dependencies: dequal: 2.0.3 @@ -4317,41 +4639,14 @@ snapshots: ansi-colors: 4.1.3 strip-ansi: 6.0.1 + entities@7.0.1: {} + error-ex@1.3.4: dependencies: is-arrayish: 0.2.1 es-module-lexer@2.1.0: {} - esbuild@0.25.12: - optionalDependencies: - '@esbuild/aix-ppc64': 0.25.12 - '@esbuild/android-arm': 0.25.12 - '@esbuild/android-arm64': 0.25.12 - '@esbuild/android-x64': 0.25.12 - '@esbuild/darwin-arm64': 0.25.12 - '@esbuild/darwin-x64': 0.25.12 - '@esbuild/freebsd-arm64': 0.25.12 - '@esbuild/freebsd-x64': 0.25.12 - '@esbuild/linux-arm': 0.25.12 - '@esbuild/linux-arm64': 0.25.12 - '@esbuild/linux-ia32': 0.25.12 - '@esbuild/linux-loong64': 0.25.12 - '@esbuild/linux-mips64el': 0.25.12 - '@esbuild/linux-ppc64': 0.25.12 - '@esbuild/linux-riscv64': 0.25.12 - '@esbuild/linux-s390x': 0.25.12 - '@esbuild/linux-x64': 0.25.12 - '@esbuild/netbsd-arm64': 0.25.12 - '@esbuild/netbsd-x64': 0.25.12 - '@esbuild/openbsd-arm64': 0.25.12 - '@esbuild/openbsd-x64': 0.25.12 - '@esbuild/openharmony-arm64': 0.25.12 - '@esbuild/sunos-x64': 0.25.12 - '@esbuild/win32-arm64': 0.25.12 - '@esbuild/win32-ia32': 0.25.12 - '@esbuild/win32-x64': 0.25.12 - escalade@3.2.0: {} escape-string-regexp@4.0.0: {} @@ -4509,6 +4804,10 @@ snapshots: flatted@3.3.3: {} + focus-trap@8.2.0: + dependencies: + tabbable: 6.4.0 + fs-extra@9.1.0: dependencies: at-least-node: 1.0.0 @@ -4571,8 +4870,30 @@ snapshots: dependencies: function-bind: 1.1.2 + hast-util-to-html@9.0.5: + dependencies: + '@types/hast': 3.0.4 + '@types/unist': 3.0.3 + ccount: 2.0.1 + comma-separated-tokens: 2.0.3 + hast-util-whitespace: 3.0.0 + html-void-elements: 3.0.0 + mdast-util-to-hast: 13.2.1 + property-information: 7.1.0 + space-separated-tokens: 2.0.2 + stringify-entities: 4.0.4 + zwitch: 2.0.4 + + hast-util-whitespace@3.0.0: + dependencies: + '@types/hast': 3.0.4 + + hookable@5.5.3: {} + html-escaper@2.0.2: {} + html-void-elements@3.0.0: {} + human-id@4.1.3: {} iconv-lite@0.7.0: @@ -4692,6 +5013,55 @@ snapshots: prelude-ls: 1.2.1 type-check: 0.4.0 + lightningcss-android-arm64@1.32.0: + optional: true + + lightningcss-darwin-arm64@1.32.0: + optional: true + + lightningcss-darwin-x64@1.32.0: + optional: true + + lightningcss-freebsd-x64@1.32.0: + optional: true + + lightningcss-linux-arm-gnueabihf@1.32.0: + optional: true + + lightningcss-linux-arm64-gnu@1.32.0: + optional: true + + lightningcss-linux-arm64-musl@1.32.0: + optional: true + + lightningcss-linux-x64-gnu@1.32.0: + optional: true + + lightningcss-linux-x64-musl@1.32.0: + optional: true + + lightningcss-win32-arm64-msvc@1.32.0: + optional: true + + lightningcss-win32-x64-msvc@1.32.0: + optional: true + + lightningcss@1.32.0: + dependencies: + detect-libc: 2.1.2 + optionalDependencies: + lightningcss-android-arm64: 1.32.0 + lightningcss-darwin-arm64: 1.32.0 + lightningcss-darwin-x64: 1.32.0 + lightningcss-freebsd-x64: 1.32.0 + lightningcss-linux-arm-gnueabihf: 1.32.0 + lightningcss-linux-arm64-gnu: 1.32.0 + lightningcss-linux-arm64-musl: 1.32.0 + lightningcss-linux-x64-gnu: 1.32.0 + lightningcss-linux-x64-musl: 1.32.0 + lightningcss-win32-arm64-msvc: 1.32.0 + lightningcss-win32-x64-msvc: 1.32.0 + lines-and-columns@1.2.4: {} locate-path@6.0.0: @@ -4724,6 +5094,8 @@ snapshots: dependencies: semver: 7.7.3 + mark.js@8.11.1: {} + mdast-util-from-markdown@2.0.2: dependencies: '@types/mdast': 4.0.4 @@ -4746,6 +5118,18 @@ snapshots: '@types/mdast': 4.0.4 unist-util-is: 6.0.1 + mdast-util-to-hast@13.2.1: + dependencies: + '@types/hast': 3.0.4 + '@types/mdast': 4.0.4 + '@ungap/structured-clone': 1.3.0 + devlop: 1.1.0 + micromark-util-sanitize-uri: 2.0.1 + trim-lines: 3.0.1 + unist-util-position: 5.0.0 + unist-util-visit: 5.0.0 + vfile: 6.0.3 + mdast-util-to-markdown@2.1.2: dependencies: '@types/mdast': 4.0.4 @@ -4914,6 +5298,8 @@ snapshots: minimist@1.2.8: {} + minisearch@7.2.0: {} + mri@1.2.0: {} ms@2.1.3: {} @@ -4951,6 +5337,14 @@ snapshots: dependencies: wrappy: 1.0.2 + oniguruma-parser@0.12.2: {} + + oniguruma-to-es@4.3.6: + dependencies: + oniguruma-parser: 0.12.2 + regex: 6.1.0 + regex-recursion: 6.0.2 + optionator@0.9.4: dependencies: deep-is: 0.1.4 @@ -5011,6 +5405,8 @@ snapshots: pathe@2.0.3: {} + perfect-debounce@2.1.0: {} + picocolors@1.1.1: {} picomatch@2.3.1: {} @@ -5019,7 +5415,7 @@ snapshots: pirates@4.0.7: {} - postcss@8.5.6: + postcss@8.5.13: dependencies: nanoid: 3.3.11 picocolors: 1.1.1 @@ -5031,6 +5427,8 @@ snapshots: propagate@2.0.1: {} + property-information@7.1.0: {} + proto-list@1.2.4: {} punycode@2.3.1: {} @@ -5052,6 +5450,16 @@ snapshots: regenerate@1.4.2: {} + regex-recursion@6.0.2: + dependencies: + regex-utilities: 2.3.0 + + regex-utilities@2.3.0: {} + + regex@6.1.0: + dependencies: + regex-utilities: 2.3.0 + regexpu-core@6.4.0: dependencies: regenerate: 1.4.2 @@ -5087,36 +5495,29 @@ snapshots: reusify@1.1.0: {} - rollup@2.79.2: + rolldown@1.0.0-rc.17: + dependencies: + '@oxc-project/types': 0.127.0 + '@rolldown/pluginutils': 1.0.0-rc.17 optionalDependencies: - fsevents: 2.3.3 + '@rolldown/binding-android-arm64': 1.0.0-rc.17 + '@rolldown/binding-darwin-arm64': 1.0.0-rc.17 + '@rolldown/binding-darwin-x64': 1.0.0-rc.17 + '@rolldown/binding-freebsd-x64': 1.0.0-rc.17 + '@rolldown/binding-linux-arm-gnueabihf': 1.0.0-rc.17 + '@rolldown/binding-linux-arm64-gnu': 1.0.0-rc.17 + '@rolldown/binding-linux-arm64-musl': 1.0.0-rc.17 + '@rolldown/binding-linux-ppc64-gnu': 1.0.0-rc.17 + '@rolldown/binding-linux-s390x-gnu': 1.0.0-rc.17 + '@rolldown/binding-linux-x64-gnu': 1.0.0-rc.17 + '@rolldown/binding-linux-x64-musl': 1.0.0-rc.17 + '@rolldown/binding-openharmony-arm64': 1.0.0-rc.17 + '@rolldown/binding-wasm32-wasi': 1.0.0-rc.17 + '@rolldown/binding-win32-arm64-msvc': 1.0.0-rc.17 + '@rolldown/binding-win32-x64-msvc': 1.0.0-rc.17 - rollup@4.53.3: - dependencies: - '@types/estree': 1.0.8 + rollup@2.79.2: optionalDependencies: - '@rollup/rollup-android-arm-eabi': 4.53.3 - '@rollup/rollup-android-arm64': 4.53.3 - '@rollup/rollup-darwin-arm64': 4.53.3 - '@rollup/rollup-darwin-x64': 4.53.3 - '@rollup/rollup-freebsd-arm64': 4.53.3 - '@rollup/rollup-freebsd-x64': 4.53.3 - '@rollup/rollup-linux-arm-gnueabihf': 4.53.3 - '@rollup/rollup-linux-arm-musleabihf': 4.53.3 - '@rollup/rollup-linux-arm64-gnu': 4.53.3 - '@rollup/rollup-linux-arm64-musl': 4.53.3 - '@rollup/rollup-linux-loong64-gnu': 4.53.3 - '@rollup/rollup-linux-ppc64-gnu': 4.53.3 - '@rollup/rollup-linux-riscv64-gnu': 4.53.3 - '@rollup/rollup-linux-riscv64-musl': 4.53.3 - '@rollup/rollup-linux-s390x-gnu': 4.53.3 - '@rollup/rollup-linux-x64-gnu': 4.53.3 - '@rollup/rollup-linux-x64-musl': 4.53.3 - '@rollup/rollup-openharmony-arm64': 4.53.3 - '@rollup/rollup-win32-arm64-msvc': 4.53.3 - '@rollup/rollup-win32-ia32-msvc': 4.53.3 - '@rollup/rollup-win32-x64-gnu': 4.53.3 - '@rollup/rollup-win32-x64-msvc': 4.53.3 fsevents: 2.3.3 run-parallel@1.2.0: @@ -5139,6 +5540,17 @@ snapshots: shebang-regex@3.0.0: {} + shiki@3.23.0: + dependencies: + '@shikijs/core': 3.23.0 + '@shikijs/engine-javascript': 3.23.0 + '@shikijs/engine-oniguruma': 3.23.0 + '@shikijs/langs': 3.23.0 + '@shikijs/themes': 3.23.0 + '@shikijs/types': 3.23.0 + '@shikijs/vscode-textmate': 10.0.2 + '@types/hast': 3.0.4 + siginfo@2.0.0: {} slash@3.0.0: {} @@ -5154,12 +5566,19 @@ snapshots: sourcemap-codec@1.4.8: {} + space-separated-tokens@2.0.2: {} + stackback@0.0.2: {} std-env@4.1.0: {} strict-event-emitter@0.5.1: {} + stringify-entities@4.0.4: + dependencies: + character-entities-html4: 2.1.0 + character-entities-legacy: 3.0.0 + strip-ansi@6.0.1: dependencies: ansi-regex: 5.0.1 @@ -5172,6 +5591,8 @@ snapshots: supports-preserve-symlinks-flag@1.0.0: {} + tabbable@6.4.0: {} + tapable@2.3.3: {} terser@5.44.1: @@ -5190,12 +5611,19 @@ snapshots: fdir: 6.5.0(picomatch@4.0.4) picomatch: 4.0.4 + tinyglobby@0.2.16: + dependencies: + fdir: 6.5.0(picomatch@4.0.4) + picomatch: 4.0.4 + tinyrainbow@3.1.0: {} to-regex-range@5.0.1: dependencies: is-number: 7.0.0 + trim-lines@3.0.1: {} + ts-api-utils@2.5.0(typescript@6.0.3): dependencies: typescript: 6.0.3 @@ -5205,6 +5633,9 @@ snapshots: picomatch: 4.0.4 typescript: 6.0.3 + tslib@2.8.1: + optional: true + type-check@0.4.0: dependencies: prelude-ls: 1.2.1 @@ -5239,6 +5670,10 @@ snapshots: dependencies: '@types/unist': 3.0.3 + unist-util-position@5.0.0: + dependencies: + '@types/unist': 3.0.3 + unist-util-stringify-position@4.0.0: dependencies: '@types/unist': 3.0.3 @@ -5270,23 +5705,81 @@ snapshots: validate-npm-package-name@6.0.2: {} - vite@7.2.7(@types/node@24.12.2)(terser@5.44.1): + vfile-message@4.0.3: dependencies: - esbuild: 0.25.12 - fdir: 6.5.0(picomatch@4.0.4) + '@types/unist': 3.0.3 + unist-util-stringify-position: 4.0.0 + + vfile@6.0.3: + dependencies: + '@types/unist': 3.0.3 + vfile-message: 4.0.3 + + vite@8.0.10(@types/node@24.12.2)(terser@5.44.1): + dependencies: + lightningcss: 1.32.0 picomatch: 4.0.4 - postcss: 8.5.6 - rollup: 4.53.3 - tinyglobby: 0.2.15 + postcss: 8.5.13 + rolldown: 1.0.0-rc.17 + tinyglobby: 0.2.16 optionalDependencies: '@types/node': 24.12.2 fsevents: 2.3.3 terser: 5.44.1 - vitest@4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@7.2.7): + vitepress@2.0.0-alpha.17(@types/node@24.12.2)(postcss@8.5.13)(terser@5.44.1)(typescript@6.0.3): + dependencies: + '@docsearch/css': 4.6.3 + '@docsearch/js': 4.6.3 + '@docsearch/sidepanel-js': 4.6.3 + '@iconify-json/simple-icons': 1.2.80 + '@shikijs/core': 3.23.0 + '@shikijs/transformers': 3.23.0 + '@shikijs/types': 3.23.0 + '@types/markdown-it': 14.1.2 + '@vitejs/plugin-vue': 6.0.6(vite@8.0.10)(vue@3.5.33) + '@vue/devtools-api': 8.1.1 + '@vue/shared': 3.5.33 + '@vueuse/core': 14.3.0(vue@3.5.33) + '@vueuse/integrations': 14.3.0(focus-trap@8.2.0)(vue@3.5.33) + focus-trap: 8.2.0 + mark.js: 8.11.1 + minisearch: 7.2.0 + shiki: 3.23.0 + vite: 8.0.10(@types/node@24.12.2)(terser@5.44.1) + vue: 3.5.33(typescript@6.0.3) + optionalDependencies: + postcss: 8.5.13 + transitivePeerDependencies: + - '@types/node' + - '@vitejs/devtools' + - async-validator + - axios + - change-case + - drauu + - esbuild + - fuse.js + - idb-keyval + - jiti + - jwt-decode + - less + - nprogress + - qrcode + - sass + - sass-embedded + - sortablejs + - stylus + - sugarss + - terser + - tsx + - typescript + - universal-cookie + - yaml + + vitest@4.1.5(@types/node@24.12.2)(@vitest/coverage-v8@4.1.5)(vite@8.0.10): dependencies: '@vitest/expect': 4.1.5 - '@vitest/mocker': 4.1.5(vite@7.2.7) + '@vitest/mocker': 4.1.5(vite@8.0.10) '@vitest/pretty-format': 4.1.5 '@vitest/runner': 4.1.5 '@vitest/snapshot': 4.1.5 @@ -5303,7 +5796,7 @@ snapshots: tinyexec: 1.0.2 tinyglobby: 0.2.15 tinyrainbow: 3.1.0 - vite: 7.2.7(@types/node@24.12.2)(terser@5.44.1) + vite: 8.0.10(@types/node@24.12.2)(terser@5.44.1) why-is-node-running: 2.3.0 optionalDependencies: '@types/node': 24.12.2 @@ -5311,6 +5804,16 @@ snapshots: transitivePeerDependencies: - msw + vue@3.5.33(typescript@6.0.3): + dependencies: + '@vue/compiler-dom': 3.5.33 + '@vue/compiler-sfc': 3.5.33 + '@vue/runtime-dom': 3.5.33 + '@vue/server-renderer': 3.5.33(vue@3.5.33) + '@vue/shared': 3.5.33 + optionalDependencies: + typescript: 6.0.3 + which@2.0.2: dependencies: isexe: 2.0.0 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index a21e18b65..824d9063f 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,6 +1,7 @@ packages: - packages/* - scripts/* + - site allowBuilds: esbuild: false @@ -9,3 +10,6 @@ dedupePeers: true dedupePeerDependents: true shellEmulator: true + +overrides: + 'vitepress>vite': ^8.0.0 diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts new file mode 100644 index 000000000..02c2e1e65 --- /dev/null +++ b/site/.vitepress/config.ts @@ -0,0 +1,146 @@ +import { defineConfig } from "vitepress"; + +export default defineConfig({ + title: "Changesets", + head: [["link", { rel: "icon", href: "logo.svg" }]], + + lastUpdated: true, + cleanUrls: true, + + themeConfig: { + logo: "/logo.svg", + editLink: { + pattern: "https://github.com/changesets/changesets/edit/main/site/:path", + }, + + socialLinks: [ + { icon: "github", link: "https://github.com/changesets/changesets" }, + ], + + search: { + provider: "local", + }, + + nav: [ + { + text: "Guide", + link: "/guide/intro/what-are-changesets", + }, + { + text: "Lib", + link: "/lib/apply-release-plan", + }, + { + text: "FAQ", + link: "/faq/publishing-in-monorepos", + }, + ], + + sidebar: { + "/guide": { + base: "guide", + items: [ + { + text: "Intro", + base: "/guide/intro/", + items: [ + { text: "What are Changesets", link: "what-are-changesets" }, + { text: "Concepts", link: "concepts" }, + { text: "Dictionary", link: "dictionary" }, + { text: "Getting Stared", link: "getting-started" }, + ], + }, + { + text: "Basic", + base: "/guide/basic/", + items: [ + { text: "Adding a Changeset", link: "adding-a-changeset" }, + { + text: "Automating Changesets", + link: "automating-changesets", + }, + { + text: "Checking for Changesets", + link: "checking-for-changesets", + }, + { text: "Configuration", link: "configuration" }, + ], + }, + { + text: "Advance", + base: "/guide/advance/", + items: [ + { text: "Fixed Packages", link: "fixed-packages" }, + { text: "Linked Packages", link: "linked-packages" }, + { + text: "Modifying Changelog Format", + link: "modifying-changelog-format", + }, + { text: "Pre Releases", link: "pre-releases" }, + { text: "Snapshot Releases", link: "snapshot-releases" }, + { text: "Versioning Apps", link: "versioning-apps" }, + ], + }, + { + text: "Api Reference", + base: "/guide/api/", + items: [{ text: "CLI", link: "cli" }], + }, + ], + }, + "/faq": { + base: "faq", + items: [ + { + base: "/faq/", + items: [ + { + text: "Pushing in Monorepos?", + link: "publishing-in-monorepos", + }, + ], + }, + ], + }, + "/lib": { + base: "lib", + items: [ + { + base: "/lib/", + items: [ + { text: "apply-release-plan", link: "apply-release-plan" }, + { + text: "assemble-release-plan", + link: "assemble-release-plan", + }, + { text: "changelog-git", link: "changelog-git" }, + { text: "changelog-github", link: "changelog-github" }, + { text: "cli", link: "cli" }, + { text: "git", link: "git" }, + { text: "pre", link: "pre" }, + { text: "release-utils", link: "release-utils" }, + { text: "get-release-plan", link: "get-release-plan" }, + { text: "get-github-info", link: "get-github-info" }, + { + text: "get-version-range-type", + link: "get-version-range-type", + }, + { + text: "get-dependents-graph", + link: "get-dependents-graph", + }, + { text: "logger", link: "logger" }, + { text: "parse", link: "parse" }, + { text: "should-skip-package", link: "should-skip-package" }, + { text: "types", link: "types" }, + { text: "config", link: "config" }, + { text: "errors", link: "errors" }, + { text: "read", link: "read" }, + { text: "write", link: "write" }, + ], + }, + ], + }, + }, + }, +}); diff --git a/site/.vitepress/theme/custom.css b/site/.vitepress/theme/custom.css new file mode 100644 index 000000000..ccb83fb02 --- /dev/null +++ b/site/.vitepress/theme/custom.css @@ -0,0 +1,32 @@ +@media (min-width: 640px) { + .VPHero .container .main .text { + font-size: 48px !important; + } +} + +:root { + --vp-c-brand-1: #124787; + --vp-c-brand-2: #165db3; + --vp-c-brand-3: #5bb7f3; + + --vp-home-hero-name-background: linear-gradient( + 135deg, + #124787 10%, + #5bb7f3 100% + ); + + --vp-home-hero-image-background-image: linear-gradient( + -60deg, + #a5ccf9 50%, + #65baf6 50% + ); + --vp-home-hero-image-filter: blur(50px); + + --vp-button-brand-border: #124787; + --vp-button-brand-text: #f4f8fd; + --vp-button-brand-bg: #124787; + + --vp-button-brand-hover-border: #165db3; + --vp-button-brand-hover-text: #fff; + --vp-button-brand-hover-bg: #165db3; +} \ No newline at end of file diff --git a/site/.vitepress/theme/index.ts b/site/.vitepress/theme/index.ts new file mode 100644 index 000000000..a9e217fd2 --- /dev/null +++ b/site/.vitepress/theme/index.ts @@ -0,0 +1,5 @@ +import DefaultTheme from "vitepress/theme"; +import "./style.css"; +import "./custom.css"; + +export default DefaultTheme; diff --git a/site/.vitepress/theme/style.css b/site/.vitepress/theme/style.css new file mode 100644 index 000000000..8702981dd --- /dev/null +++ b/site/.vitepress/theme/style.css @@ -0,0 +1,138 @@ +/** + * Customize default theme styling by overriding CSS variables: + * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css + */ + +/** + * Colors + * + * Each colors have exact same color scale system with 3 levels of solid + * colors with different brightness, and 1 soft color. + * + * - `XXX-1`: The most solid color used mainly for colored text. It must + * satisfy the contrast ratio against when used on top of `XXX-soft`. + * + * - `XXX-2`: The color used mainly for hover state of the button. + * + * - `XXX-3`: The color for solid background, such as bg color of the button. + * It must satisfy the contrast ratio with pure white (#ffffff) text on + * top of it. + * + * - `XXX-soft`: The color used for subtle background such as custom container + * or badges. It must satisfy the contrast ratio when putting `XXX-1` colors + * on top of it. + * + * The soft color must be semi transparent alpha channel. This is crucial + * because it allows adding multiple "soft" colors on top of each other + * to create a accent, such as when having inline code block inside + * custom containers. + * + * - `default`: The color used purely for subtle indication without any + * special meanings attached to it such as bg color for menu hover state. + * + * - `brand`: Used for primary brand colors, such as link text, button with + * brand theme, etc. + * + * - `tip`: Used to indicate useful information. The default theme uses the + * brand color for this by default. + * + * - `warning`: Used to indicate warning to the users. Used in custom + * container, badges, etc. + * + * - `danger`: Used to show error, or dangerous message to the users. Used + * in custom container, badges, etc. + * -------------------------------------------------------------------------- */ + +:root { + --vp-c-default-1: var(--vp-c-gray-1); + --vp-c-default-2: var(--vp-c-gray-2); + --vp-c-default-3: var(--vp-c-gray-3); + --vp-c-default-soft: var(--vp-c-gray-soft); + + --vp-c-brand-1: var(--vp-c-indigo-1); + --vp-c-brand-2: var(--vp-c-indigo-2); + --vp-c-brand-3: var(--vp-c-indigo-3); + --vp-c-brand-soft: var(--vp-c-indigo-soft); + + --vp-c-tip-1: var(--vp-c-brand-1); + --vp-c-tip-2: var(--vp-c-brand-2); + --vp-c-tip-3: var(--vp-c-brand-3); + --vp-c-tip-soft: var(--vp-c-brand-soft); + + --vp-c-warning-1: var(--vp-c-yellow-1); + --vp-c-warning-2: var(--vp-c-yellow-2); + --vp-c-warning-3: var(--vp-c-yellow-3); + --vp-c-warning-soft: var(--vp-c-yellow-soft); + + --vp-c-danger-1: var(--vp-c-red-1); + --vp-c-danger-2: var(--vp-c-red-2); + --vp-c-danger-3: var(--vp-c-red-3); + --vp-c-danger-soft: var(--vp-c-red-soft); +} + +/** + * Component: Button + * -------------------------------------------------------------------------- */ + +:root { + --vp-button-brand-border: transparent; + --vp-button-brand-text: var(--vp-c-white); + --vp-button-brand-bg: var(--vp-c-brand-3); + --vp-button-brand-hover-border: transparent; + --vp-button-brand-hover-text: var(--vp-c-white); + --vp-button-brand-hover-bg: var(--vp-c-brand-2); + --vp-button-brand-active-border: transparent; + --vp-button-brand-active-text: var(--vp-c-white); + --vp-button-brand-active-bg: var(--vp-c-brand-1); +} + +/** + * Component: Home + * -------------------------------------------------------------------------- */ + +:root { + --vp-home-hero-name-color: transparent; + --vp-home-hero-name-background: -webkit-linear-gradient( + 120deg, + #bd34fe 30%, + #41d1ff + ); + + --vp-home-hero-image-background-image: linear-gradient( + -45deg, + #bd34fe 50%, + #47caff 50% + ); + --vp-home-hero-image-filter: blur(44px); +} + +@media (min-width: 640px) { + :root { + --vp-home-hero-image-filter: blur(56px); + } +} + +@media (min-width: 960px) { + :root { + --vp-home-hero-image-filter: blur(68px); + } +} + +/** + * Component: Custom Block + * -------------------------------------------------------------------------- */ + +:root { + --vp-custom-block-tip-border: transparent; + --vp-custom-block-tip-text: var(--vp-c-text-1); + --vp-custom-block-tip-bg: var(--vp-c-brand-soft); + --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft); +} + +/** + * Component: Algolia + * -------------------------------------------------------------------------- */ + +.DocSearch { + --docsearch-primary-color: var(--vp-c-brand-1) !important; +} diff --git a/site/faq/publishing-in-monorepos.md b/site/faq/publishing-in-monorepos.md new file mode 100644 index 000000000..c99bf7af6 --- /dev/null +++ b/site/faq/publishing-in-monorepos.md @@ -0,0 +1,5 @@ +# Problems Publishing in Monorepos + +Monorepos have a heap of complexity around how publishing to npm works. Changesets helps most repository users avoid ever having to think about these problems, however repository maintainers, especially those who want to customise how their releases work (for example those not using our [github action](https://github.com/changesets/action/)), may want to understand what it is solving for you. + +TODO: flesh this out (sorry it's not done yet) diff --git a/site/guide/advance/fixed-packages.md b/site/guide/advance/fixed-packages.md new file mode 100644 index 000000000..5ff54a3e9 --- /dev/null +++ b/site/guide/advance/fixed-packages.md @@ -0,0 +1,50 @@ +# Fixed Packages + +Fixed packages allow you to specify a group or groups of packages that should be versioned and published together. + +> [!NOTE] +> Unlike `linked packages`, all packages in the group of fixed packages will be version-bumped and published together even when there are no changes done to some of the the member packages. + +## Examples + +I have three packages, `pkg-a`, `pkg-b` and `pkg-c`. `pkg-a` and `pkg-b` are fixed but `pkg-c` is not so the config looks like this. + +```json +{ + "fixed": [["pkg-a", "pkg-b"]] +} +``` + +- `pkg-a` is at `1.0.0` +- `pkg-b` is at `1.0.0` +- `pkg-c` is at `1.0.0` + +I have a changeset with a patch for `pkg-a`, minor for `pkg-b` and major for `pkg-c` and I do a release, the resulting versions will be: + +- `pkg-a` is at `1.1.0` +- `pkg-b` is at `1.1.0` +- `pkg-c` is at `2.0.0` + +I now have another changeset with a minor for `pkg-a` and I do a release, the resulting versions will be: + +- `pkg-a` is at `1.2.0` +- `pkg-b` is at `1.2.0` +- `pkg-c` is at `2.0.0` + +## Using glob expressions + +Sometimes you want to fix many or all packages within your project (for example in a monorepo setup), in which case you would need to keep the list of fixed packages up-to-date. + +To make it simpler to maintain that list, you can provide glob expressions in the list that would match and resolve to all the packages that you wish to include. + +For example: + +```json +{ + "fixed": [["pkg-*"]] +} +``` + +It will match all packages starting with `pkg-`. + +**The glob expressions must be defined according to the [micromatch](https://www.npmjs.com/package/micromatch) format.** diff --git a/site/guide/advance/linked-packages.md b/site/guide/advance/linked-packages.md new file mode 100644 index 000000000..c7f049e02 --- /dev/null +++ b/site/guide/advance/linked-packages.md @@ -0,0 +1,90 @@ +# Linked Packages + +Linked packages allow you to specify a group or groups of packages that should be versioned together. There are some complex cases, so some examples are shown below to demonstrate various cases. + +- Linked packages will still only be bumped when there is a changeset for them (this can mean because you explicitly choose to add a changeset for it or because it's a dependent of something being released) +- Packages that have changesets and are in a set of linked packages will **always** be versioned to the highest current version in the set of linked packages + the highest bump type from changesets in the set of linked packages + +> [!NOTE] +> Unlike `fixed packages`, there is no guarantee that all packages in the group of linked packages will be version-bumped and published, only those with changeset(s) will be. + +## Examples + +### General example + +I have three packages, `pkg-a`, `pkg-b` and `pkg-c`. `pkg-a` and `pkg-b` are linked but `pkg-c` is not so the config looks like this. + +```json +{ + "linked": [["pkg-a", "pkg-b"]] +} +``` + +- `pkg-a` is at `1.0.0` +- `pkg-b` is at `1.0.0` +- `pkg-c` is at `1.0.0` + +I have a changeset with a patch for `pkg-a`, minor for `pkg-b` and major for `pkg-c` and I do a release, the resulting versions will be: + +- `pkg-a` is at `1.1.0` +- `pkg-b` is at `1.1.0` +- `pkg-c` is at `2.0.0` + +I now have another changeset with a minor for `pkg-a` and I do a release, the resulting versions will be: + +- `pkg-a` is at `1.2.0` +- `pkg-b` is at `1.1.0` +- `pkg-c` is at `2.0.0` + +I now have another changeset with a minor for `pkg-b` and I do a release, the resulting versions will be: + +- `pkg-a` is at `1.2.0` +- `pkg-b` is at `1.3.0` +- `pkg-c` is at `2.0.0` + +I now have another changeset with patches for all three packages and I do a release, the resulting versions will be: + +- `pkg-a` is at `1.3.1` +- `pkg-b` is at `1.3.1` +- `pkg-c` is at `2.0.1` + +### Example with dependants + +I have two packages, `pkg-a`, `pkg-b` which are linked. `pkg-a` has a dependency on `pkg-b`. + +```json +{ + "linked": [["pkg-a", "pkg-b"]] +} +``` + +- `pkg-a` is at `1.0.0` +- `pkg-b` is at `1.0.0` + +I have a changeset with a major for `pkg-b` and I do a release, the resulting versions will be: + +- `pkg-a` is at `2.0.0` +- `pkg-b` is at `2.0.0` + +I now have another changeset with a major for `pkg-a` and I do a release, the resulting versions will be: + +- `pkg-a` is at `3.0.0` +- `pkg-b` is at `2.0.0` + +## Using glob expressions + +Sometimes you want to link many or all packages within your project (for example in a monorepo setup), in which case you would need to keep the list of linked packages up-to-date. + +To make it simpler to maintain that list, you can provide glob expressions in the linked list that would match and resolve all the packages you wish to include. + +For example: + +```json +{ + "linked": [["pkg-*"]] +} +``` + +It will match all packages starting with `pkg-`. + +**The glob expressions must be defined according to the [micromatch](https://www.npmjs.com/package/micromatch) format.** diff --git a/site/guide/advance/modifying-changelog-format.md b/site/guide/advance/modifying-changelog-format.md new file mode 100644 index 000000000..9b48f54c8 --- /dev/null +++ b/site/guide/advance/modifying-changelog-format.md @@ -0,0 +1,82 @@ +# Modifying The Changelog Formats + +Changesets comes with a default format for the changelogs for packages which is relatively basic in what information it displays, however this is customisable. Here we will talk about how to modify the changelog, so that it contains extra meta-information. + +## Setting What Formatting Functions to Use + +To change how the changelog is generated, you use the `changelog` setting in the `./changeset/config.json`. This setting accepts a string, which points to a module. You can reference an npm package that you have installed, or a local file where you have written your own functions. + +For example, `changesets` has a package, `@changesets/changelog-git`. To use it, you would first need to install the package. + +```bash +yarn add @changesets/changelog-git +``` + +Next, change your `.changeset/config.json` to point to the new package: + +``` +"changelog": "@changesets/changelog-git" +``` + +If you want to write your own, you can reference a file path. For example, you can create a new file `.changeset/my-changelog-config.js`, then you can reference it in the `.changeset/config.json` file as: + +``` +"changelog": "./my-changelog-config.js" +``` + +## Writing Changelog Formatting Functions + +The changelog formatting is done by two different functions. `getReleaseLine` and `getDependencyReleaseLine`. These must be provided in an object as the export of your generation file. A basic file setup for the changelog generation functions would be: + +```js +async function getReleaseLine() {} + +async function getDependencyReleaseLine() {} + +module.exports = { + getReleaseLine, + getDependencyReleaseLine, +}; +``` + +These functions are run during the `changeset version` and are expected to return a string (or a promise with a string). + +If you are using typescript to write your changelog functions, you can use the type. First install `@changesets/types`, and then: + +```ts +import { ChangelogFunctions } from "@changesets/types"; + +async function getReleaseLine() {} + +async function getDependencyReleaseLine() {} + +const defaultChangelogFunctions: ChangelogFunctions = { + getReleaseLine, + getDependencyReleaseLine, +}; + +export default defaultChangelogFunctions; +``` + +```ts +type getReleaseLine( + changeset: { + // This is the string of the summary from the changeset markdown file + summary: string + // This is an array of information about what is going to be released. each is an object with name: the name of the package, and type, which is "major", "minor", or "patch" + releases + // the hash for the commit that introduced the changeset + commit + }, + // the type of the change this changeset refers to, as "major", "minor", or "patch" + type + // This needs to be explained - see @changesets/changelog-github's code for how this works + changelogOpts +) => string +``` + +> TODO - this guide is incomplete. Until it is completed, you may need to dig into the code for some of our existing + +## Adding Options to Changelog Functions + +> TODO diff --git a/site/guide/advance/pre-releases.md b/site/guide/advance/pre-releases.md new file mode 100644 index 000000000..023879159 --- /dev/null +++ b/site/guide/advance/pre-releases.md @@ -0,0 +1,143 @@ +# Prereleases + +> [!WARNING] +> Pre releases are very complicated! Using them requires a thorough understanding of all parts of npm publishes. Mistakes can lead to repository and publish states that are very hard to fix. + +> [!WARNING] +> If you decide to do prerelease from the main branch of your repository, without having a branch for your last stable release without the prerelease changes, you will block other changes until you are ready to exit prerelease mode. We thoroughly recommend only running prerelease from a branch other than the main branch. + +You might want to release a version of your packages before you do an actual release, Changesets lets you do this but there are some caveats because of the complexity that monorepos add that are important to understand. + +When you want to do a prerelease, you need to enter prerelease mode. You can do that with the `pre enter `. The tag that you need to pass is used in versions(e.g. `1.0.0-beta.0`) and for the npm dist tag. + +A prerelease workflow might look something like this: + +```bash +yarn changeset pre enter next +yarn changeset version +git add . +git commit -m "Enter prerelease mode and version packages" +yarn changeset publish +git push --follow-tags +``` + +Let's go through what's happening here. For this example, let's say you have a repo that looks like this: + +``` +packages/ + pkg-a@1.0.0 has dep on pkg-b@^2.0.0 + pkg-b@2.0.0 has no deps + pkg-c@3.0.0 has no deps +.changeset/ + pkg-b@minor +``` + +```bash +yarn changeset pre enter next +``` + +This command changes Changesets into prerelease mode which creates a `pre.json` file in the `.changeset` directory which stores information about the state the prerelease is in. For the specific data stored in the `pre.json` file, see the type definition of `PreState` in [`@changesets/types`](https://github.com/changesets/changesets/tree/main/packages/types). + +```bash +yarn changeset version +``` + +This command will version packages as you would normally expect but append `-next.0`. An important note is that this will bump dependent packages that wouldn't be bumped in normal releases because prerelease versions are not satisfied by most semver ranges.(e.g. `^5.0.0` is not satisfied by `5.1.0-next.0`) + +The repo would now look like this: + +``` +packages/ + pkg-a@1.0.1-next.0 has dep on pkg-b@^2.0.1 + pkg-b@2.1.0-next.0 has no deps + pkg-c@3.0.0 has no deps +.changeset/ +``` + +```bash +yarn changeset publish +``` + +This command will publish to npm as the publish command normally does though it will set the dist tag to the tag you specified when running the prerelease command. + +When you want to do another prerelease, your workflow would look something like this: + +```bash +yarn changeset version +git add . +git commit -m "Version packages" +yarn changeset publish +git push --follow-tags +``` + +Let's say we add some changesets and a new package so our repo looks like this + +``` +packages/ + pkg-a@1.0.1-next.0 has dep on pkg-b@^2.0.1 + pkg-b@2.1.0-next.0 has no deps + pkg-c@3.0.0 has no deps + pkg-d@0.0.0 has no deps + +.changeset/ + pkg-a@minor + pkg-c@patch + pkg-d@major +``` + +```bash +yarn changeset version +``` + +The version command will behave just like it does for the first versioning of a prerelease except the number at the end will be updated. The repo would now look like this: + +``` +packages/ + pkg-a@1.1.0-next.1 has dep on pkg-b@^2.0.1 + pkg-b@2.1.0-next.0 has no deps + pkg-c@3.0.1-next.0 has no deps + pkg-d@1.0.0-next.0 has no deps +``` + +```bash +yarn changeset publish +``` + +This command will publish to npm just like it does for the first prerelease except because we're adding a new package(we need to define this, is it new to the repo or new to npm? I'm thinking new to npm), the new package will be published with the `latest` dist tag rather than the `next` tag because it's the first time it's being published which means it will be on `latest` anyway. For future publishes until pkg-d is out of prerelease, it will also be published to `latest`. + +When you're ready to do the final release, your workflow would look something like this: + +```bash +yarn changeset pre exit +yarn changeset version +git add . +git commit -m "Exit prerelease mode and version packages" +yarn changeset publish +git push --follow-tags +``` + +```bash +yarn changeset pre exit +``` + +This command will set an intent to exit prerelease mode in the `pre.json` file though it won't do any actual versioning. + +```bash +yarn changeset version +``` + +The version command will apply any changesets currently in the repo and then remove the prerelease tag from the versions. The repo would now look like this: + +``` +packages/ + pkg-a@1.1.0 has dep on pkg-b@^2.0.1 + pkg-b@2.1.0 has no deps + pkg-c@3.0.1 has no deps + pkg-d@1.0.0 has no deps +``` + +```bash +yarn changeset publish +``` + +The publish command will publish everything to the `latest` dist tag as normal. diff --git a/site/guide/advance/snapshot-releases.md b/site/guide/advance/snapshot-releases.md new file mode 100644 index 000000000..12239d184 --- /dev/null +++ b/site/guide/advance/snapshot-releases.md @@ -0,0 +1,53 @@ +# Snapshot Releases + +Snapshot releases are a way to release your changes for testing without updating the versions. Both a modified `version` and a modified `publish` command are used to do accomplish a snapshot release. After both processes run, you will have a published version of packages in changesets with a version of `0.0.0-{tag}-DATETIMESTAMP`. + +## Starting Off + +Create changesets as normal, as described in [adding a changeset](/guide/basic/adding-a-changeset). When you are ready to release a snapshot, you should make a dedicated branch for doing so. + +## Versioning your packages + +```bash +yarn changeset version --snapshot +``` + +This will apply the changesets, but instead of using the next version, all versions will be set to `0.0.0-THE_TIME_YOU_DID_THIS`. + +If you want to add a personalised part to this version number, such as `bulbasaur`, you can run + +```bash +yarn changeset version --snapshot bulbasaur +``` + +This will instead update versions to `0.0.0-bulbasaur-THE_TIME_YOU_DID_THIS` + +## Publishing your packages + +After running the `yarn changeset version` command, you can use the `changeset publish --tag bulbasaur` command to release the packages. By using the `--tag` flag, you will not add it to the `latest` flag on npm. This is REALLY IMPORTANT because if you do not include a tag, people installing your package using `yarn add your-package-name` will install the snapshot version. + +## Using the `--no-git-tag` flag + +You can use the `--no-git-tag` CLI flag when running `changeset publish` if you plan to publish snapshot releases locally or you are pushing [git tags](http://npm.github.io/publishing-pkgs-docs/updating/using-tags.html) to a remote from your CI environment. + +When you run `changeset publish --no-git-tag --snapshot`, changesets will skip creating git tags for published snapshot packages. That means that git tags can still be created whenever pushing stable versions (with a regular `changeset publish`), and you can safely publish snapshot releases locally, without creating unnecessary tags. + +## Using a snapshot version + +When you want to get people to test your snapshots, they can either update their package.json to your newly published version and run an install, or use `yarn add your-package-name@YOUR_TAG_OR_VERSIONS` + +For our above example, you could run + +```bash +yarn add your-package-name@0.0.0-bulbasaur-THE_TIME_YOU_DID_THIS +``` + +or the tag: + +```bash +yarn add your-package-name@bulbasaur +``` + +## What to do with the snapshot branch + +In almost all circumstances, we recommend that the changes after you have run `version` get merged back into your main branch. With snapshots, this is not the case. We recommend that you do not push the changes from this running of `version` to any branch. This is because the snapshot is intended for installation only, not to represent the correct published state of the repo. Save the generated version, and the tag you used, but do not push this to a branch you are planning to merge into the main branch, or merge it into the main branch. diff --git a/site/guide/advance/versioning-apps.md b/site/guide/advance/versioning-apps.md new file mode 100644 index 000000000..b553e9bd5 --- /dev/null +++ b/site/guide/advance/versioning-apps.md @@ -0,0 +1,22 @@ +# Managing Applications or Non-npm Packages + +Changesets can also be used to manage application versions or non-npm packages (ie dotnet NuGet packages, ruby gems, docker images etc). + +The only requirement is that the project has a package.json file to manage the versions and dependencies within the repo. + +To enable this feature set `privatePackages` to `{ version: true, tag: true }` in your `.changesets/config.json` file. By default changesets will only update the changelog and version (ie `{ version: true, tag: false }`). + +> [!NOTE] +> Changesets only versions NPM package.json files, you can trigger releases for other package formats by creating workflows which trigger on tags/releases being created by changesets. + +## Setting up a package + +To enable a project to be tracked by changesets, it needs a minimal package.json with at least `name`, `private` and `version`. + +```json +{ + "name": "my-project", + "private": true, + "version": "0.0.1" +} +``` diff --git a/site/guide/api/cli.md b/site/guide/api/cli.md new file mode 100644 index 000000000..1eb74175d --- /dev/null +++ b/site/guide/api/cli.md @@ -0,0 +1,158 @@ +# Command line options + +The command line for changesets is the main way of interacting with it. There are 4 main commands. If you are looking for how we recommend you setup and manage changesets with the commands, check out our [intro to using changesets](/guide/intro/getting-started) + +- init +- add [--empty][--open] +- version [--ignore, --snapshot] +- publish [--otp=code, --tag] +- status [--since=master --verbose --output=JSON_FILE.json] +- pre [exit|enter {tag}] +- tag + +The most important commands are `add`, which is used by contributors to add information about their changes, `version` - which is responsible for using the changesets generated by `add` to update package versions and changelogs, and then `publish` which publishes changes to npm. + +## `init` + +```bash +changeset init +``` + +This command sets up the .changeset folder. It generates a readme and a config file. The config file includes the default options and comments on what these options represent. You should run this command once when you are setting up changesets. + +## `add` + +```bash +changeset add +``` + +or just + +```bash +changeset +``` + +This is the main command people use to interact with the changesets. + +This command will ask you a series of questions, first about what packages you want to release, then what semver bump type for each package, then it will ask for a summary of the entire changeset. The final step will show the changeset it will generate and confirm that you want to add it. + +Once confirmed, the changeset will be written a Markdown file that contains the summary and YAML front matter which stores the packages that will be released and the semver bump types for them. + +A changeset that major bumps @changesets/cli would look like this: + +```md +--- +"@changesets/cli": major +--- + +A description of the major changes. +If you want to modify this file after it's generated, that's completely fine or if you want to write changeset files yourself, that's also fine. +``` + +- `--empty` - allows you to create an empty changeset if no packages are being bumped, usually only required if you have CI that blocks merges without a changeset. + +```bash +changeset --empty +``` + +A changeset created with the empty flag would look like this: + +```md +--- +--- +``` + +If you set the commit option in the config, the command will add the updated changeset files and then commit them. + +- `--open` - opens the created changeset in an external editor + +## version + +```bash +changeset version +``` + +This is one of two commands responsible for releasing packages. The version command takes changesets that have been made and updates versions and dependencies of packages, as well as writing changelogs. It is responsible for all file changes to versions before publishing to npm. + +> [!TIP] +> We recommend making sure changes made from this command are merged back into the base branch before you run publish. + +Version has two options, `ignore` and `snapshot`: + +```bash +changeset version --ignore PACKAGE_NAME +``` + +This command is used to allow you to skip packages from being published. This allows you to run partial publishes of the repository. Using ignore has some safety rails: + +1. If the package is mentioned in a changeset that also includes a package that is not ignored, publishing will fail. +2. If the package requires one of its dependencies to be updated as part of a publish. + +These restrictions exist to ensure your repository or published code does not end up in a broken state. For additional information on the intricacies of publishing, check out our guide on [problems publishing in monorepos](/faq/publishing-in-monorepos). + +```bash +changeset version --snapshot +``` + +Snapshot is used for a special kind of publishing for testing - it creates temporary versions with a tag, instead of updating versions from the current semver ranges. You should not use this without [reading the documentation on snapshot releases](/guide/advance/snapshot-releases) + +## publish + +```bash +changeset publish [--otp={token}] +``` + +This publishes changes to npm, and creates git tags. This works by going into each package, checking if the version it has in its `package.json` is published on npm, and if it is not, running the `npm publish`. If you are using `pnpm` as a package manager, this automatically detects it and uses `pnpm publish` instead. + +Because this command assumes that the last commit is the release commit, you should not commit any changes between calling version and publish. These commands are separate to enable you to check if the release changes are accurate. + +`--otp={token}` - allows you to provide an npm one-time password if you have auth and writes enabled on npm. The CLI also prompts for the OTP if it's not provided with the --otp option. + +`--tag TAGNAME` - for packages that are published, the chosen tag will be used instead of `latest`, allowing you to publish changes intended for testing and validation, not main consumption. This will most likely be used with [snapshot releases](/guide/advance/snapshot-releases). + +### Git Tags + +It is useful to have git tags of a publish, to allow people looking for the code at that time to find them. We generate tags in git during publish, but you will need to push them back up if you want to make them available. We recommend after publish you run: + +```bash +git push --follow-tags +``` + +## status + +```bash +status [--verbose] [--output={filePath}] [--since={gitTag}] +``` + +The status command provides information about the changesets that currently exist. If there are no changesets present, it exits with an error status code. + +- `--verbose` - use if you want to know the new versions, and get a link to the relevant changeset summary. + +- `--output` - allows you to write the JSON object of the status output for consumption by other tools, such as CI. + +- `--since` - to only display information about changesets since a specific branch or git tag (such as `main`, or the git hash of latest). While this can be used to add a CI check for changesets, we recommend not doing this. We instead recommend using the [changeset bot](https://github.com/apps/changeset-bot) to detect pull requests missing changesets, as not all pull requests need one if you are on GitHub. + +> [!NOTE] > `status` will fail if you are in the middle of running `version` or `publish`. If you want to get changeset status at the time of a version increase and publish, you need to run it immediately before running `version`. + +## pre + +```bash +pre [exit|enter {tag}] +``` + +The pre command enters and exits pre mode. The command does not do any actual versioning, when doing a pre-release, you should run changeset pre enter next(or a different tag, the tag is what is in versions and is the npm dist tag) and then do the normal release process with changeset version and changeset publish. For more information about the pre command, see the prereleases [the prereleases documentation](/guide/advance/pre-releases). + +> [!CAUTION] +> pre-releases are a very complicated feature. Many of the safety rails that changesets helps you with will be taken off. We recommend that you read both [problems publishing in monorepos](/faq/publishing-in-monorepos) and be clear on both exiting and entering pre-releases before using it. You may also prefer using [snapshot releases](/guide/advance/snapshot-releases) for a slightly less involved process. + +## tag + +```bash +tag +``` + +The tag command creates git tags for the current version of all packages. The tags created are equivalent to those created by [`changeset publish`](#publish), but the `tag` command does not publish anything to npm. + +This is helpful in situations where a different tool, such as `pnpm publish -r`, is used to publish packages instead of changeset. For situations where `changeset publish` is executed, running `changeset tag` is not needed. + +The git tags in monorepos are created in the format `pkg-name@version-number` and are based on the current version number of the `package.json` for each package. Note that in single-package repositories, the git tag will include `v` before the version number, for example, `v1.0.0`. It is expected that [`changeset version`](#version) is run before `changeset tag`, so the `package.json` versions are updated before the git tags are created. diff --git a/site/guide/basic/adding-a-changeset.md b/site/guide/basic/adding-a-changeset.md new file mode 100644 index 000000000..4922b882a --- /dev/null +++ b/site/guide/basic/adding-a-changeset.md @@ -0,0 +1,71 @@ +# Adding a Changeset + +Hi! You might be here because a person or a bot has asked you to 'add a changeset' to a project. Let's walk through adding a changeset. But first, what is a changeset? + +## What is a changeset? + +A changeset is a piece of information about changes made in a branch or commit. It holds three bits of information: + +- What we need to release +- What version we are releasing packages at (using a [semver bump type](https://semver.org/)) +- A changelog entry for the released packages + +## I am in a multi-package repository (a mono-repo) + +1. Run the command line script `npx changeset` or `yarn changeset`. +2. Select the packages you want to include in the changeset using ↑ and ↓ to navigate to packages, and space to select a package. Hit enter when all desired packages are selected. +3. You will be prompted to select a bump type for each selected package. Select an appropriate bump type for the changes made. See [here](https://semver.org/) for information on semver versioning +4. Your final prompt will be to provide a message to go alongside the changeset. This will be written into the changelog when the next release occurs. + +After this, a new changeset will be added which is a markdown file with YAML front matter. + +``` +-| .changeset/ +-|-| UNIQUE_ID.md +``` + +The message you typed can be found in the markdown file. If you want to expand on it, you can write as much markdown as you want, which will all be added to the changelog on publish. If you want to add more packages or change the bump types of any packages, that's also fine. + +While not every changeset is going to need a huge amount of detail, a good idea of what should be in a changeset is: + +- WHAT the change is +- WHY the change was made +- HOW a consumer should update their code + +5. Once you are happy with the changeset, commit the file to your branch. + +## I am in a single-package repository + +1. Run the command line script `npx changeset` or `yarn changeset`. +2. Select an appropriate bump type for the changes made. See [here](https://semver.org/) for information on semver versioning +3. Your final prompt will be to provide a message to go alongside the changeset. This will be written into the changelog when the next release occurs. + +After this, a new changeset will be added which is a markdown file with YAML front matter. + +``` +-| .changeset/ +-|-| UNIQUE_ID.md +``` + +The message you typed can be found in the markdown file. If you want to expand on it, you can write as much markdown as you want, which will all be added to the changelog on publish. If you want to change the bump type for the changeset, that's also fine. + +While not every changeset is going to need a huge amount of detail, a good idea of what should be in a changeset is: + +- WHAT the change is +- WHY the change was made +- HOW a consumer should update their code + +4. Once you are happy with the changeset, commit the file to your branch. + +## Tips on adding changesets + +### You can add more than one changeset to a pull request + +Changesets are designed to stack, so there's no problem with adding multiple. You might want to add more than one changeset when: + +- You want to release multiple packages with different changelog entries +- You have made multiple changes to a package that should each be called out separately + +## I want to know more about changesets + +[here is the concepts of changesets](/guide/intro/concepts) diff --git a/site/guide/basic/automating-changesets.md b/site/guide/basic/automating-changesets.md new file mode 100644 index 000000000..8a88c6d11 --- /dev/null +++ b/site/guide/basic/automating-changesets.md @@ -0,0 +1,55 @@ +# Automating Changesets + +While changesets are designed to work with a fully manual process, it also provides tools to help automate these releases. These can be broken into two major decisions: + +1. How do I want to ensure pull requests have changesets? +2. How do I run the version and publish commands? + +Here we have a quick-start recommended workflow, with more + +## Recommended Automation Flow + +1. Install our [changeset bot](https://github.com/apps/changeset-bot) into your repository. +2. Add the [github action](https://github.com/changesets/action) to your repository. + +## How do I want to ensure pull requests have changesets? + +Changesets are committed to files, so a diligent reviewer can always technically tell if a changeset is absent and request one be added. As humans though, a file not being there is easy to miss. We recommend adding some way to detect the presence or absence of changesets on a pull request so you don't have to, as well as highlight it to pull-request makers so you don't have to. + +This has two main approaches. + +### Non-blocking + +In this approach, a pull request may be merged if no changeset is present, and a missing changeset does not create a red build. Our [github changeset bot](https://github.com/apps/changeset-bot) is the best way to prompt for changesets without making them blocking. As a handy extra feature, they give you a link to add your own changeset as a maintainer to smooth over merging pull requests without waiting for the contributor to add a changeset. + +### Blocking + +Sometimes, you may want to make CI fail if no changeset is present to ensure no PR can be merged without a changeset. To do this: + +In your CI process, add a step that runs: + +```bash +changeset status --since=main +``` + +This will exit with exit code 1 if there have been no new changesets since main. + +In some cases, you may _want_ to merge a change without doing any releases (such as when you only change tests or build tools). In this case, you can run `changeset --empty`. This will add a special changeset that does not release anything. + +## How do I run the version and publish commands? + +We have a [github action](https://github.com/changesets/action) that + +- creates a `version` PR, then keeps it up to date, recreating it when merged. This PR always has an up-to-date run of `changeset version` +- Optionally allows you to do releases when changes are merged to the base branch. + +If you don't want to use this action, the manual workflow we recommend for running the `version` and `publish` commands is: + +- A release coordinator (RC) calls to stop any merging to the base branch +- The RC pulls down the base branch, runs `changeset version`, then makes a new PR with the versioning changes +- The versioning changes are merged back into the base branch +- The RC pulls the base branch again and runs `changeset publish` +- The RC runs `git push --follow-tags` to push the release tags back +- The RC unblocks merging to the base branch + +This is a lot of steps and is quite finicky (we have to pull from the base branch twice). Feel free to finesse it to your own circumstances. diff --git a/site/guide/basic/checking-for-changesets.md b/site/guide/basic/checking-for-changesets.md new file mode 100644 index 000000000..57eac139d --- /dev/null +++ b/site/guide/basic/checking-for-changesets.md @@ -0,0 +1,13 @@ +# Checking for Changesets + +[//]: # "todo: replace the link below with a link to the docs" + +Using `@changesets/cli`, there is a `status` command. See the docs for it in the +[@changesets/cli](/lib/cli#status) + +We have a [github bot](https://github.com/apps/changeset-bot) and a +[bitbucket addon](https://bitbucket.org/atlassian/atlaskit-mk-2/src/master/build/bitbucket-release-addon/) that +alert users of missing changesets. + +If you want to cause a failure in CI on missing changesets (not recommended), you can run `changeset status --since=main`, +which will exit with a status code of 1 if there are no new changesets. diff --git a/site/guide/basic/configuration.md b/site/guide/basic/configuration.md new file mode 100644 index 000000000..356e3ea50 --- /dev/null +++ b/site/guide/basic/configuration.md @@ -0,0 +1,255 @@ +# Configuring Changesets + +Changesets has a minimal amount of configuration options. Mostly these are for when you need to change the default workflows. These are stored in `.changeset/config.json`. Our default config is: + +```json +{ + "commit": false, + "updateInternalDependencies": "patch", + "linked": [], + "access": "restricted", + "baseBranch": "master", + "ignore": [], + "changelog": "@changesets/cli/changelog" +} +``` + +> [!NOTE] +> The `linked`, `fixed`, `updateInternalDependencies`, `bumpVersionsWithWorkspaceProtocolOnly`, and `ignore` options are only for behaviour in monorepos. + +## `commit` + +> [!NOTE] Type: +> +> - `boolean` +> - `string`(module path) +> - a tuple like `[modulePath: string, options: any]` + +This option is for setting if the `changeset add` command and the `changeset version` commands will also add and commit the changed files using git, and how the commit messages should be generated for them. + +By default, we do not commit the files, and leave it to the user to commit the files. If it is `true`, we use the default commit message generator (`["@changesets/cli/commit", { "skipCI": "version" }]`). Setting it to a string and options tuple specifies a path from where we will load the commit message generation functions. It expects to be a file that exports one or both of the following: + +``` +{ + getAddMessage, + getVersionMessage +} +``` + +If one of the methods is not present then we will not commit the files changed for that command. + +You would specify a custom commit message generator with: + +```json +{ + "commit": ["../scripts/commit.js", { "customOption": true }] +} +``` + +This is similar to how the [changelog generator functions work](#changelog). + +## `access` + +> [!NOTE] Type: +> +> - `restricted` +> - `public` + +This sets how packages are published - if `access: "restricted"`, packages will be published as private, requiring log in to an npm account with access to install. If `access: "public"`, the packages will be made available on the public registry. + +By default, npm publishes scoped npm packages as `restricted` - so to ensure you do not accidentally publish code publicly, we default to `restricted`. For most cases you will want to set this to `public`. + +This can be overridden in specific packages by setting the `access` in a package's `package.json`. + +If you want to prevent a package from being published to npm, set `private: true` in that package's `package.json` + +## `baseBranch` + +> [!NOTE] Type: +> +> - `string` (git branch name) + +The branch to which changesets will make comparisons. A number of internal changesets features use git to compare present changesets against another branch. This defaults what branch will be used for these comparisons. This should generally set to the major branch you merge changes into. Commands that use this information accept a `--since` option which can be used to override this. + +> [!TIP] +> To help make coding a more inclusive experience, we recommend changing the name of your `master` branch to `main`. + +## `ignore` + +> [!NOTE] Type: +> +> - `string[]` (names of packages) + +This option allows you to specify some packages that will not be published, even if they are referenced in changesets. Instead, those changesets will be skipped until they are removed from this array. + +> [!IMPORTANT] +> THIS FEATURE IS DESIGNED FOR TEMPORARY USE TO ALLOW CHANGES TO BE MERGED WITHOUT PUBLISHING THEM - If you want to stop a package from being published at all, set `private: true` in its `package.json`. + +There are two caveats to this. + +1. If the package is mentioned in a changeset that also includes a package that is not ignored, publishing will fail. +2. If the package requires one of its dependencies to be updated as part of a publish. + +These restrictions exist to ensure your repository or published code do not end up in a broken state. For a more detailed intricacies of publishing, check out our guide on [problems publishing in monorepos](/faq/publishing-in-monorepos). + +> [!TIP] +> You can also provide glob expressions to match the packages, according to the [micromatch](https://www.npmjs.com/package/micromatch) format. + +## `fixed` + +> [!NOTE] Type: +> +> - `string[][]` (array of arrays of package names) + +This option can be used to declare that packages should be version-bumped and published together. As an example, if you have a `@changesets/button` component and a `@changesets/theme` component and you want to make sure that when one gets bumped to `1.1.0`, the other is also bumped to `1.1.0` regardless if it has any change or not. To achieve this you would have the config: + +```json +{ + "fixed": [["@changesets/button", "@changesets/theme"]] +} +``` + +If you want to use this option, you should read the documentation on [fixed packages](/guide/advance/fixed-packages) to fully understand the implementation and implications. + +## `linked` + +> [!NOTE] Type: +> +> - `string[][]` (array of arrays of package names) + +This option can be used to declare that packages should 'share' a version, instead of being versioned completely independently. As an example, if you have a `@changesets/button` component and a `@changesets/theme` component and you want to make sure that when one gets bumped to `2.0.0`, the other is also bumped to `2.0.0`. To achieve this you would have the config: + +```json +{ + "linked": [["@changesets/button", "@changesets/theme"]] +} +``` + +If you want to use this option, you should read the documentation on [linked packages](/guide/advance/linked-packages) to fully understand the implementation and implications. + +> [!CAUTION] +> This does not do what some other tools do, which is make sure when any package is published, all other packages are also published with the same version. + +## `updateInternalDependencies` + +> [!NOTE] Type: +> +> - `out-of-range` +> - `always` + +This option sets whether, when a package that is being depended upon changes, whether you should update what version it depends on. To make this more understandable, here is an example: + +Say we have two packages, one depending on the other: + +``` +pkg-a @ version 1.0.0 +pkg-b @ version 1.0.0 + depends on pkg-a at range `^1.0.0 +``` + +Say we are publishing a patch of both `pkg-a` and `pkg-b` - this flag is for determining whether we update how `pkg-b` depends on `pkg-a`. + +If the option is set to `patch`, we will update the dependency so we will now have: + +``` +pkg-a @ version 1.0.1 +pkg-b @ version 1.0.1 + depends on pkg-a at range `^1.0.1 +``` + +If however the option is set to `minor`, what it depends on will only be updated when there is a minor change, so the state would be: + +``` +pkg-a @ version 1.0.1 +pkg-b @ version 1.0.1 + depends on pkg-a at range `^1.0.0 +``` + +Using `minor` allows consumers to more actively control their own deduplication of packages, and will allow them to install fewer versions if you have many interconnected packages. Using `patch` will mean consumers will more often be using more updated code, but may cause problems with deduplication. + +Changesets will always update the dependency if it would leave the old semver range. + +> [!WARNING] +> This is only applied for packages which are already released in the current release. If A depends on B and we only release B then A won't be bumped. + +## `changelog` + +> [!NOTE] Type: +> +> - `false` +> - `string` (path to a file) + +This option is for setting how the changelog for packages should be generated. If it is `false`, no changelogs will be generated. Setting it to a string specifies a path from where we will load the changelog generation functions. It expects to be a file that exports the following: + +``` +{ + getReleaseLine, + getDependencyReleaseLine +} +``` + +As well as the default one, you can use `@changesets/changelog-git`, which adds links to commits into changelogs, or `@changesets/changelog-github`, which requires github authentication, and includes a thankyou message to the person who added the changeset as well as a link to the relevant PR. + +You would specify our github changelog generator with: + +```json +{ + "changelog": ["@changesets/changelog-github", { "repo": "/" }] +} +``` + +For more details on these functions and information on how to write your own see [changelog-functions](/guide/advance/modifying-changelog-format) + +## `bumpVersionsWithWorkspaceProtocolOnly` + +> [!NOTE] Type: +> +> - `boolean` + +Determines whether Changesets should only bump dependency ranges that use workspace protocol of packages that are part of the workspace. + +## `snapshot` + +> [!NOTE] Type +> +> - `object` (optional) + +Default value: `undefined` + +### `useCalculatedVersion` + +> [!NOTE] Type: +> +> - `boolean` (optional) + +Default value: `false` + +When `changesets version --snapshot` is used, the default behavior is to use `0.0.0` as the base version for the snapshot release. + +Setting `useCalculatedVersion: true` will change the default behavior and will use the calculated version, based on the changeset files. + +### `prereleaseTemplate` + +> [!NOTE] Type: +> +> - `string` (optional) + +Default value: `undefined` (see note below) + +Configures the suffix for the snapshot releases, using a template with placeholders. + +**Available placeholders:** + +You can use the following placeholders for customizing the snapshot release version: + +- `{tag}` - the name of the snapshot tag, as specified in `--snapshot something` +- `{commit}` - the Git commit ID +- `{timestamp}` - Unix timestamp of the time of the release +- `{datetime}` - date and time of the release (14 characters, for example, `20211213000730`) + +> [!WARNING] +> If you are using `--snapshot` with empty tag name, you cannot use `{tag}` as placeholder - this will result in error. + +**Default behavior** + +If you are not specifying `prereleaseTemplate`, the default behavior will fall back to using the following template: `{tag}-{datetime}`, and in cases where the tag is empty (`--snapshot` with no tag name), it will use `{datetime}` only. diff --git a/site/guide/intro/concepts.md b/site/guide/intro/concepts.md new file mode 100644 index 000000000..f5cbfb8c5 --- /dev/null +++ b/site/guide/intro/concepts.md @@ -0,0 +1,61 @@ +# The core concepts of changesets + +Below, you will find a detailed explanation of what changesets are, and how they are being thought about. + +## The problem: + +When organising the release of packages, you may end up wanting to group several changes together written by different people and/or over a relatively large period of time. The best time to capture this information is when submitting a PR (when it is fresh in your mind), not when you eventually go to batch and release these changes. + +Git is a bad place to store this information, as it discourages writing detailed change descriptions - you want to allow people to provide as much documentation for the change as they want. + +## The solution, Changesets: + +The best way to think about a changeset as separate to either a changelog or a version bump is that a changeset is an 'intent to change'. The intent to change carries with it two key bits of information: + +- versioning +- changelogs + +As it is an intent to change, the relevant versioning information is: + +- 'major' | 'minor' | 'patch' + +In addition, within a mono-repository, we can encode information about any other packages in the mono-repository that should be re-released to consume this change. This ensures that if you upgrade latest of all the packages, they are all compatible. The current implementation is heavily informed by [bolt's](https://github.com/boltpkg/bolt) opinion on version compatibility. + +- changelog information can be stored as a markdown snippet. + +As storing this information directly in git is problematic, we store it in the file system using the following structure: + +``` +-| .changeset/ +-|-| UNIQUE_ID.md +``` + +A changeset is a Markdown file with YAML front matter. The contents of the Markdown is the change summary which will be written to the changelog and the YAML front matter describes what packages have changed and what semver bump types they should be + +```md +--- +"@myproject/cli": major +"@myproject/core": minor +--- + +Change all the things +``` + +This is useful because it breaks versioning into two steps: + +1. Adding a changeset - can be done in a PR, by a contributor, while the change is fresh in their mind. +2. Versioning - combines all changesets, creates one version bump for each package based on the maximum version bump of each package, and updates dependencies where needed, write changelogs. Can then be reviewed as an aggregate. + +## The tooling that makes this worthwhile + +1. CLI generation of new changesets +2. Automated consumption of changesets to do versioning +3. Detection + surfacing of changesets in PRs + +A tool to publish multiple packages from a mono-repo is also important, however does not need to be linked to this. + +## Benefits to single-package repos + +Changesets are designed first and foremost to handle versioning in multi-package repos, where interdependencies flowing through the system are important to understand and capture. + +Conceptually though, the benefits of changesets are detachable from this. I think this process overall leads to an improvement in Pull Requests that helps increase confidence in versioning decisions and changelog entries. diff --git a/site/guide/intro/dictionary.md b/site/guide/intro/dictionary.md new file mode 100644 index 000000000..5f3e7d60e --- /dev/null +++ b/site/guide/intro/dictionary.md @@ -0,0 +1,34 @@ +# Changesets Dictionary + +This is a list of some words and phrases that are used in changesets which are helpful to know so that contributors to changesets have a shared understanding of various concepts in the project. + +Several of these have associated type definitions, which you can find in [our types package](https://github.com/changesets/changesets/blob/main/packages/types/src/index.ts). + +- **changeset** - an intent to release a set of packages at particular bump types with a summary of the changes made. Changesets are stackable, that is running `bump` will apply any number of changesets correctly. Changesets are used to generate further information, such as the `release information`, and the `release plan`. +- **summary** - Information about the changes the changeset represents - this is written out to the `CHANGELOG.md` file of every package mentioned in the changeset. +- **changeset folder** - A `./changeset` folder - this is where we store written versions of changesets. Currently we assume all changesets are written to this. +- **workspace** - a local package in a multi-package repo +- **bump-type** - The type of change expected. Of type `major | minor | patch | none`, based on the change types of [semver](https://semver.org/) +- **range-type** - The type of range a package depends on, such as `1.0.0`, `~1.0.0`, or `^1.0.0`. This is a subset of valid semver ranges as [defined by node](https://github.com/npm/node-semver#ranges), narrowing to ranges we can update programmatically. +- **bump** + - (1) The command to apply all current changesets and update all package versions and changelogs. + - (2) The act of updating a package version to a new version. +- **single-package repo** - A repository which only contains a single package which is at the root of the repo +- **multi-package repo/monorepo** - A repository which contains multiple packages, generally managed by [Bolt](https://github.com/boltpkg/bolt) or [Yarn Workspaces](https://yarnpkg.com/lang/en/docs/workspaces/). +- **release line generators** - The `getReleaseLine` and `getDependencyReleaseLine` functions which are responsible for creating the lines inserted into changelog. A changelog entry for a particular release can be thought of as `releaseLineGenerators(changesets)` +- **fixed packages** - Fixed packages share a semver categorisation, such that all fixed packages have the same semver version and are always published together. The logistics of this are best left to our [fixed-packages](/guide/advance/fixed-packages) documentation. +- **linked packages** - Linked packages share a semver categorisation, such that all published linked packages have consistent new semver ranges. The logistics of this are best left to our [linked-packages](/guide/advance/linked-packages) documentation. +- **release instruction** An object containing an intent to release a single package, consisting of the package name and a bump type +- **release plan** - A calculated object that shows everything a collection of changesets will release, and at what version, and how. This object includes a calculation of dependencies, and considerations for `linked` packages. +- **absolutely correct semver** - making semver versioning decisions to ensure nothing less than major is capable of breaking a consumer's code. Because literally any change is technically capable of breaking a user's code, absolutely correct semver requires that all changes are major changes. +- **pragmatically correct semver** - Making semver decisions that you believe to be correct, but may be in error. A pragmatic assessment is likely to change with the number of users of a project, and the API surface area of the project. Whenever we talk about 'correct semver', we are referring to 'pragmatically correct semver' +- **dependency** - A package that is depended upon by another given package. +- **dependent** - A package which depends on another given package. This is frequently used in the context of the getting the dependents of a package so they can be released. +- **release** - The combination of versioning and publishing a package or packages which may include a build process before publishing +- **prereleases** - A pre-release is a release that uses a tag, and is not published as `latest` on npm. This is designed for when you want to share code, but are not yet ready for it to be the main package used by everyone. Pre-releases for packages are common, but pre-releases within a monorepo presents unique problems. You can see our exhaustive pre-release documentation [in our prereleases documentation](/guide/advance/pre-releases). In addition, there are two different approaches to pre-releases which are defined for use separately. +- **Release Candidate (RC) prerelease** - An RC prerelease is done before an intended important release, likely a major release. It includes semver information about what the next intended release version is, a tag, and an iterated number for the prerelease. The output of this is intended to be committed, and then further work done on the branch. An example would be if I am on `1.0.0` of a package, and I want to do an RC for the next `major` version we would have: `package-one@2.0.0-my-tag.0`, and then the next publish is `package-one@2.0.0-my-tag.1`. +- **snapshot prerelease** - A snapshot pre-release is intended to make it easy to test all changes at a particular git commit. It is published at `0.0.0` and uses the git hash as the tag. This should be used as a less formal method than a release candidate to make it easy to install and test changes. An example, if we have a package at `1.0.0`, and have a changeset for it to be `major` bumped, a snapshot release will be at `0.0.0-ABCDEFGH` (the last github hash). If we add more commits, the next snapshot would be `0.0.0-HIJKLMNOP`. + +## Things that we haven't figured out how to explain well yet + +- The fact that a package is depending on a package and what the range of the dependency is specified in the list of the package's dependencies. This is specifically not about the dependency but about the relationship between the dependent and the dependency. diff --git a/site/guide/intro/getting-started.md b/site/guide/intro/getting-started.md new file mode 100644 index 000000000..0ff65346f --- /dev/null +++ b/site/guide/intro/getting-started.md @@ -0,0 +1,90 @@ +# Using changesets + +Changesets are designed to make your workflows easier, by allowing the person making contributions to make key decisions when they are making their contribution. Changesets hold two key bits of information: a version type (following [semver](https://semver.org/)), and change information to be added to a changelog. + +In addition, changesets were originally designed for implementation in [bolt monorepos](https://github.com/boltpkg/bolt). As such, in a monorepo context, changesets will handle bumping dependencies of changed packages, if that is required. + +This guide is aimed at package maintainers adding changesets as a tool. For the information relevant to contributors, see [adding a changeset](/guide/basic/adding-a-changeset). + +The overall tool after initialization should lead to a loop that looks like: + +1. Changesets added along with each change +2. The version command is run when a release is ready, and the changes are verified +3. The publish command is run afterward. + +The second two steps can be made part of a CI process. + +## Add the changeset tool + +```shell +npm install @changesets/cli && npx changeset init +``` + +or + +```shell +yarn add @changesets/cli && yarn changeset init +``` + +or + +```shell +pnpm i @changesets/cli && pnpm changeset init +``` + +## Adding changesets + +```shell +npx changeset +``` + +or + +```shell +yarn changeset +``` + +or + +```shell +pnpm changeset +``` + +> [!TIP] +> Note: You can run `changeset add` to add a changeset if you want to, but running Changesets without any command works as well. + +## Versioning and publishing + +Once you decide you want to do a release, you can run + +```shell +npx changeset version +``` + +or + +```shell +yarn changeset version +``` + +This consumes all changesets, and updates to the most appropriate semver version based on those changesets. It also writes changelog entries for each consumed changeset. + +We recommend at this step reviewing both the changelog entries and the version changes for packages. Once you are confident that these are correct, and have made any necessary tweaks to changelogs, you can publish your packages: + +```shell +npx changeset publish +``` + +or + +```shell +yarn changeset publish +``` + +This will run npm publish in each package that is of a later version than the one currently listed on npm. + +## Some handy advice + +### Not every change requires a changeset + +Since changesets are focused on releases and changelogs, changes to your repository that don't require these won't need a changeset. As such, we recommend not adding a blocking element to contributions in the absence of a changeset. diff --git a/site/guide/intro/what-are-changesets.md b/site/guide/intro/what-are-changesets.md new file mode 100644 index 000000000..3e1e71d08 --- /dev/null +++ b/site/guide/intro/what-are-changesets.md @@ -0,0 +1,14 @@ +# What are changesets? + +The changesets workflow is designed to help when people are making changes, all the way through to publishing. It lets contributors declare how their changes should be released, then we automate updating `package versions`, and `changelogs`, and `publishing new versions` of packages based on the provided information. + +Changesets has a focus on solving these problems for multi-package repositories, and keeps packages that rely on each other within the multi-package repository up-to-date, as well as making it easy to make changes to groups of packages. + +> [!NOTE] +> Just want to try it out? Skip to the [Getting Started](/guide/intro/getting-started) page. + +## How do we do that? + +A changeset is an intent to release a set of packages at particular semver bump types with a summary of the changes made. + +The `@changesets/cli` package allows you to write changeset files as you make changes, then combine `any number of changesets` into a release, that flattens the bump-types into a single release per package, handles internal dependencies in a multi-package-repository, and updates changelogs, as well as release all updated packages from a mono-repository with one command. diff --git a/site/index.md b/site/index.md new file mode 100644 index 000000000..a36b338aa --- /dev/null +++ b/site/index.md @@ -0,0 +1,35 @@ +--- +# https://vitepress.dev/reference/default-theme-home-page +layout: home + +hero: + name: "Changesets" + text: "Version and Changelogs" + tagline: A tool to manage versioning and changelogs + image: + src: /logo.svg + alt: Changesets logo + actions: + - theme: brand + text: Get Started + link: /guide/intro/what-are-changesets + - theme: alt + text: View on GitHub + link: https://github.com/changesets/changesets + +features: + - icon: ⚡ + title: Automated Versioning + details: Automatically updates versions based on change types, ensuring consistent dependencies. + - icon: 📦 + title: Support for Multi-package Repositories + details: Simplifies managing multiple packages within one repository. + - icon: 📖 + title: Change Log Generation + details: Automatically creates change logs for easy tracking of updates and new features. + - icon: 🚀 + title: CI/CD Workflow Integration + details: Streamlines version control and releases through automatic pull requests and release triggers. +--- + + diff --git a/site/lib/apply-release-plan.md b/site/lib/apply-release-plan.md new file mode 100644 index 000000000..5ecec61f9 --- /dev/null +++ b/site/lib/apply-release-plan.md @@ -0,0 +1,27 @@ +# @changesets/apply-release-plan + +[![npm package](https://img.shields.io/npm/v/@changesets/apply-release-plan)](https://npmjs.com/package/@changesets/apply-release-plan) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +This takes a `releasePlan` object for changesets and applies the expected changes from that +release. This includes updating package versions, and updating changelogs. + +```ts +import applyReleasePlan from "@changesets/apply-release-plan"; +import { ReleasePlan, Config } from "@changesets/types"; +import { Packages } from '@manypkg/get-packages' + +await applyReleasePlan( + // The release plan to be applied - see @changesets/types for information about its shape + aReleasePlan: ReleasePlan, + // The packages that applyReleasePlan should be run for from @manypkg/get-packages + packages: Packages, + // A valid @changesets/config config - see @changesets/types for information about its shape + config: Config +); +``` + +Note that `apply-release-plan` does not validate the release plan's accuracy. + +To generate a release plan from written changesets use `@changesets/get-release-plan` diff --git a/site/lib/assemble-release-plan.md b/site/lib/assemble-release-plan.md new file mode 100644 index 000000000..9393cb8b2 --- /dev/null +++ b/site/lib/assemble-release-plan.md @@ -0,0 +1,44 @@ +# @changesets/assemble-release-plan + +[![npm package](https://img.shields.io/npm/v/@changesets/assemble-release-plan)](https://npmjs.com/package/@changesets/assemble-release-plan) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +Assemble a release plan for changesets from data about a repository. + +Usage + +```ts +import assembleReleasePlan from "@changesets/assemble-release-plan"; +import readChangesets from "@changesets/read"; +import { read } from "@changesets/config"; +import { getPackages } from "@manypkg/get-packages"; +import { readPreState } from "@changesets/pre"; + +const packages = await getPackages(cwd); +const preState = await readPreState(cwd); +const config = await read(cwd, packages); +const changesets = await readChangesets(cwd, sinceRef); + +const releasePlan = assembleReleasePlan(changesets, packages, config, preState); +``` + +Signature + +```ts +import { NewChangeset, Config, ReleasePlan } from "@changesets/types"; +import { Packages } from "@manypkg/get-packages"; + +assembleReleasePlan = ( + changesets: NewChangeset[], + packages: Packages, + config: Config, +) => ReleasePlan; +``` + +This package exists so assembling a release plan can be done without reading from disc. +This is useful primarily for testing within the changesets project, and when you cannot +run commands within the repository you want a release plan for (some CI cases). + +For most cases, you should use `@changesets/get-release-plan` which will read local changeset +files, config, and workspaces, to assemble the release plan from. diff --git a/site/lib/changelog-git.md b/site/lib/changelog-git.md new file mode 100644 index 000000000..a29e75542 --- /dev/null +++ b/site/lib/changelog-git.md @@ -0,0 +1 @@ +# @changesets/git diff --git a/site/lib/changelog-github.md b/site/lib/changelog-github.md new file mode 100644 index 000000000..821f3caba --- /dev/null +++ b/site/lib/changelog-github.md @@ -0,0 +1 @@ +# @changesets/github diff --git a/site/lib/cli.md b/site/lib/cli.md new file mode 100644 index 000000000..e2bc93c3c --- /dev/null +++ b/site/lib/cli.md @@ -0,0 +1,198 @@ +# @changesets/cli 🦋 + +[![npm package](https://img.shields.io/npm/v/@changesets/cli)](https://npmjs.com/package/@changesets/cli) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +The primary implementation of [changesets](https://github.com/Noviny/changesets). Helps you manage the versioning +and changelog entries for your packages, with a focus on versioning within a mono-repository (though we support +single-package repositories too). + +This package is intended as a successor to `@atlaskit/build-releases` with a more general focus. It works in +[bolt](https://www.npmjs.com/package/bolt) multi-package repositories, [yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/) multi-package repositories, and +in single-package repositories. + +## Getting Started + +If you are installing this in a monorepo run + +``` +yarn add @changesets/cli +yarn changeset init +``` + +otherwise run + +``` +yarn add --dev @changesets/cli +yarn changeset init +``` + +From here you are set up to use changesets. Add your first changeset by running + +``` +yarn changeset +``` + +and following the prompts that you are presented with. + +Below you can find a basic workflow for maintainers to help them use changesets, which you can vary to meet your own needs. + +## Core Concepts + +The core concept that `changesets` follows is that contributors to a repository should be able to declare an intent to release, and that multiple intents should be able to be combined sensibly. Sensibly here refers to if there is one intent to release button as a 'minor' and another to release button as a 'patch', only one release will be made, at the higher of the two versions. + +A single `changeset` is an intent to release stored as data, with the information we need to combine multiple changesets and coordinate releases. It will also update internal dependencies within a multi-package repository. + +## Base workflow + +Contributor runs: + +``` +yarn changeset +``` + +or + +``` +npx changeset +``` + +and answers the provided questions. + +When the maintainer wants to release packages, they should run + +``` +yarn changeset version +``` + +or + +``` +npx changeset version +``` + +and then + +``` +yarn changeset publish +``` + +or + +``` +npx changeset publish +``` + +The commands are explained further below. + +## Commands + +### init + +``` +changeset init +``` + +This command sets up the `.changeset` folder. It generates a readme and a config file. The config file includes the default options, as well as comments on what these options represent. You should run this command once, when you are setting up `changesets`. + +To publish public packages to NPM, you'll need to edit `.changeset/config.json` and change `"access": "restricted",` to `"access": "public",`. Read more about [access in config file options](https://github.com/changesets/changesets/blob/main/docs/config-file-options.md#access-restricted--public). The `publishConfig` of each `package.json` is also respected and takes a priority over monorepo-wide setting in `.changeset/config.json`. + +### add + +``` +changeset [--empty] [--open] +``` + +or + +``` +changeset add [--empty] [--open] +``` + +This command will ask you a series of questions, first about what packages you want to release, then what semver bump type for each package, then it will ask for a summary of the entire changeset. At the final step it will show the changeset it will generate, and confirm that you want to add it. + +Once confirmed, the changeset will write a Markdown file that contains the summary and YAML front matter which stores the packages that will be released and the semver bump types for them. + +A changeset that major bumps `@changesets/cli` would look like this: + +```md +--- +"@changesets/cli": major +--- + +A description of the major changes. +``` + +If you want to modify this file after it's generated, that's completely fine or if you want to write changeset files yourself, that's also fine. + +- `--empty` - allows you to create an empty changeset if no packages are being bumped, usually only required if you have CI that blocks merges without a changeset. + +A changeset created with the `empty` flag would look like this: + +```md +--- +--- +``` + +If you set the `commit` option in the config, the command will add the updated changeset files and then commit them. + +- `--open` - opens the created changeset in an external editor + +### version + +``` +changeset version +``` + +Updates the versions for all packages described in changesets since last release along with any dependents inside the repo that are out of range. + +Will also create/append to a CHANGELOG file for each package using the summaries from the changesets. + +We recommend making sure changes made from this command are merged back into the base branch before you run `publish`. + +This command will read then delete changesets on disk, ensuring that they are only used once. + +### publish + +``` +changeset publish [--otp={token}] +``` + +Publishes to NPM repo, and creates git tags. Because this command assumes that last commit is the release commit you should not commit any changes between calling `version` and `publish`. These commands are separate to enable you to check if release commit is accurate. + +- `--otp={token}` - allows you to provide an npm one-time password if you have auth and writes enabled on npm. The CLI also prompts for the OTP if it's not provided with the `--otp` option. + +**NOTE:** You will still need to push your changes back to the base branch after this + +``` +git push --follow-tags +``` + +### status + +``` +status [--verbose] [--output={filePath}] [--since={gitTag}] +``` + +The status command provides information about the changesets that currently exist. If there are changes to packages but no changesets are present, it exits with error status code `1`. + +- `--verbose` - use if you want to know the new versions, and get a link to the relevant changeset summary. + +- `--output` - allows you to write the json object of the status out, for consumption by other tools, such as CI. + +- `--since` - to only display information about changesets since a specific branch or git tag. While this can be + used to add a CI check for changesets, we recommend not doing this. We instead recommend using the [changeset bot](https://github.com/apps/changeset-bot) + to detect pull requests missing changesets, as not all pull requests need one. + +### pre + +``` +pre [exit|enter {tag}] +``` + +The pre command enters and exits pre mode. The command does not do any actual versioning, when doing a prerelease, you should run `changeset pre enter next`(or a different tag, the tag is what is in versions and is the npm dist tag) and then do the normal release process with `changeset version` and `changeset publish`. For more information about the pre command, see [the prereleases documentation](/guide/advance/pre-releases). + +### Bumping peerDependencies + +In almost all circumstances, internal packages will be bumped as a patch. The one exception is when the dependency is a `peerDependency`, in which case the change will become a major. diff --git a/site/lib/config.md b/site/lib/config.md new file mode 100644 index 000000000..146179f06 --- /dev/null +++ b/site/lib/config.md @@ -0,0 +1,25 @@ +# @changesets/config + +> Utilities for reading and parsing Changeset's config + +[![npm package](https://img.shields.io/npm/v/@changesets/config)](https://npmjs.com/package/@changesets/config) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +```tsx +import { parse, read, ValidationError } from "@changesets/config"; + +let config = await read(process.cwd(), workspaces); + +let config = parse({ commit: true }, workspaces); + +try { + return parse({ commit: true }, workspaces); +} catch (err) { + if (err instanceof ValidationError) { + let message = err.message; + } else { + throw err; + } +} +``` diff --git a/site/lib/errors.md b/site/lib/errors.md new file mode 100644 index 000000000..119cd6239 --- /dev/null +++ b/site/lib/errors.md @@ -0,0 +1,7 @@ +# @changesets/errors + +[![npm package](https://img.shields.io/npm/v/@changesets/errors)](https://npmjs.com/package/@changesets/errors) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +Error classes for Changesets. diff --git a/site/lib/get-dependents-graph.md b/site/lib/get-dependents-graph.md new file mode 100644 index 000000000..c439033d5 --- /dev/null +++ b/site/lib/get-dependents-graph.md @@ -0,0 +1,16 @@ +# @changesets/get-dependents-graph + +[![npm package](https://img.shields.io/npm/v/@changesets/get-dependents-graph)](https://npmjs.com/package/@changesets/get-dependents-graph) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +Small helper utility extracted from bolt to get a graph of relationships between packages. + +```ts +import { getDependentsGraph } from "@changesets/get-dependents-graph"; +import { getPackages } from "@manypkg/get-packages"; + +let { graph, valid } = getDependentsGraph(await getPackages(cwd)); +``` + +Mostly published for use in [changesets](https://www.npmjs.com/package/@changesets/cli) diff --git a/site/lib/get-github-info.md b/site/lib/get-github-info.md new file mode 100644 index 000000000..868a36feb --- /dev/null +++ b/site/lib/get-github-info.md @@ -0,0 +1,85 @@ +# @changesets/get-github-info + +[![npm package](https://img.shields.io/npm/v/@changesets/get-github-info)](https://npmjs.com/package/@changesets/get-github-info) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +> Get the GitHub username and PR number from a commit. Intended for use with changesets. + +## Getting Started + +> Note: This assumes you already have changesets setup. + +To use `@changesets/get-github-info`, you'll need to install it and you'll probably also want `dotenv` to provide a GitHub personal access token via a `.env` file. + +```bash +yarn add --dev @changesets/get-github-info dotenv +``` + +or + +```bash +npm install --save-dev @changesets/get-github-info dotenv +``` + +Then you can use it in your `.changeset/config.js` like this. + +```jsx +require("dotenv").config(); +const { getInfo } = require("@changesets/get-github-info"); + +// ... + +const getReleaseLine = async (changeset, type) => { + const [firstLine, ...futureLines] = changeset.summary + .split("\n") + .map((l) => l.trimRight()); + // getInfo exposes the GH username and PR number if you want them directly + // but it also exposes a set of links for the commit, PR and GH username + let { user, pull, links } = await getInfo({ + // replace this with your own repo + repo: "Noviny/changesets", + commit: changeset.commit, + }); + let returnVal = `- ${links.commit}${ + links.pull === null ? "" : ` ${links.pull}` + }${links.user === null ? "" : ` Thanks ${links.user}!`}: ${firstLine}`; + if (futureLines.length > 0) { + returnVal += `\n${futureLines.map((l) => ` ${l}`).join("\n")}`; + } + return returnVal; +}; + +// ... +``` + +You'll need to [get a GitHub personal access token](https://github.com/settings/tokens/new) with `read:user` and `repo:status` permissions, and add it to a `.env` file. + +```bash +GITHUB_TOKEN=token_here +``` + +You can now bump your packages and changelogs with `changeset version` and it'll have the GitHub info. 🎉 + +## API + +```ts +type Info = { + user: string | null; + pull: number | null; + links: { + commit: string; + pull: string | null; + user: string | null; + }; +}; + +type Options = { + commit: string; + repo: string; +}; + +export function getInfo(options: Options): Info { + // magic... +} +``` diff --git a/site/lib/get-release-plan.md b/site/lib/get-release-plan.md new file mode 100644 index 000000000..19a06ae76 --- /dev/null +++ b/site/lib/get-release-plan.md @@ -0,0 +1,26 @@ +# @changesets/get-release-plan + +[![npm package](https://img.shields.io/npm/v/@changesets/get-release-plan)](https://npmjs.com/package/@changesets/get-release-plan) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +A function that reads information about the current repository + +```js +import getReleasePlan from "@changesets/get-release-plan"; + +const releasePlan = await getReleasePlan(cwd, since, passedConfig); +``` + +## cwd: string + +The directory to run `getReleasePlan` in - most often `process.cwd()` + +## since: string + +Sets whether to use all changesets present, or only those changesets that are new since the branch +diverged from another one. + +## passedConfig?: Config + +The changeset config options as defined in `@changesets/types`. This is optional, and can be used to overwrite any written config options. diff --git a/site/lib/get-version-range-type.md b/site/lib/get-version-range-type.md new file mode 100644 index 000000000..ac56e6b5e --- /dev/null +++ b/site/lib/get-version-range-type.md @@ -0,0 +1,10 @@ +# @changesets/get-version-range-type + +[![npm package](https://img.shields.io/npm/v/@changesets/get-version-range-type)](https://npmjs.com/package/@changesets/get-version-range-type) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +Simple function that takes in a string which is a version range (ie `^1.0.0`, `~3.5.1`, `2.0.0`) +and returns the range definition. + +A helper published mostly to ensure consistency across several changeset packages. diff --git a/site/lib/git.md b/site/lib/git.md new file mode 100644 index 000000000..1b219d8d9 --- /dev/null +++ b/site/lib/git.md @@ -0,0 +1,9 @@ +# @changesets/git + +[![npm package](https://img.shields.io/npm/v/@changesets/git)](https://npmjs.com/package/@changesets/git) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +A collection of helper functions used internally in changesets to make git operations easier. + +Published documentation is likely to remain sparse. diff --git a/site/lib/logger.md b/site/lib/logger.md new file mode 100644 index 000000000..c7a83ca1d --- /dev/null +++ b/site/lib/logger.md @@ -0,0 +1,44 @@ +# @changesets/logger + +[![npm package](https://img.shields.io/npm/v/@changesets/logger)](https://npmjs.com/package/@changesets/logger) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +### Usage + +```js +import { error } from '@changesets/logger"; + +error('message part 1', 'message part 2'); +``` + +### Package Exports + +**error**: Use `error` to print error messages upon which users which immediately action to complete the task. + +**info**: Use `info` to print informational messages to user. + +**log**: Use `log` to print messages don't fall in any other specific category. For example, message to show title of the step being performed by the changesets tool. + +**success**: Use `success` to assert to users that their instructions have completed successfully. + +**warn**: Use `warn` to print warning messages, something that user could action on now or later without much impact of their work. + +### Silencing Messages In Tests + +Use the `@changesets/test-utils` package to silence the logs in test cases. + +For example: + +```js +import { temporarilySilenceLogs } from "@changesets/test-utils"; +import { log } from "@changesets/logger"; + +temporarilySilenceLogs(); + +// Now the logs in this test file are not actually logged to std out +log("I am not logged"); + +// Use console.log to log messages in tests if required +console.log("Yay, I am logged"); +``` diff --git a/site/lib/parse.md b/site/lib/parse.md new file mode 100644 index 000000000..f26915b17 --- /dev/null +++ b/site/lib/parse.md @@ -0,0 +1,47 @@ +# @changesets/parse + +[![npm package](https://img.shields.io/npm/v/@changesets/parse)](https://npmjs.com/package/@changesets/parse) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +Parses a changeset from its written format to a data object. + +```js +import parse from "@changesets/parse"; + +const changeset = `--- +"@changesets/something": minor +"@changesets/something-else": patch +--- + +A description of a minor change`; + +const parsedChangeset = parse(changeset); +``` + +For example, it can convert: + +```md +--- +"@changesets/something": minor +"@changesets/something-else": patch +--- + +A description of a minor change +``` + +to + +```json +{ + "summary": "A description of a minor change", + "releases": [ + { "name": "@changesets/something", "type": "minor" }, + { "name": "@changesets/something-else", "type": "patch" } + ] +} +``` + +Note that this is not quite a complete Changeset for most tools as it lacks an `id`. + +For written changesets, the id is normally given as the file name, which parse is not aware of. diff --git a/site/lib/pre.md b/site/lib/pre.md new file mode 100644 index 000000000..7c8d98541 --- /dev/null +++ b/site/lib/pre.md @@ -0,0 +1,32 @@ +# @changesets/pre + +[![npm package](https://img.shields.io/npm/v/@changesets/pre)](https://npmjs.com/package/@changesets/pre) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +Enter and exit pre mode in a Changesets repo. + +## Usage + +```ts +import { enterPre, exitPre } from "@changesets/pre"; + +await enterPre(cwd, tag); + +let preState = await readPreState(cwd); + +// version packages with @changesets/cli or get a release plan and apply it +await exitPre(cwd); +``` + +This package is used by internally by Changesets to enter and exit pre mode along with reading the pre state for the `publish` and `version` commands, you should only need it if you're using `@changesets/assemble-release-plan`, implementing Changesets or want to enter or exit pre mode programmatically. + +## Types + +```ts +import { PreState } from "@changesets/types"; + +export function enterPre(cwd: string, tag: string): Promise; +export function exitPre(cwd: string): Promise; +export function readPreState(cwd: string): Promise; +``` diff --git a/site/lib/read.md b/site/lib/read.md new file mode 100644 index 000000000..5855a9320 --- /dev/null +++ b/site/lib/read.md @@ -0,0 +1,15 @@ +# @changesets/read + +[![npm package](https://img.shields.io/npm/v/@changesets/read)](https://npmjs.com/package/@changesets/read) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +Read in all changesets from a repository. + +```js +import read from "@changesets/read"; + +let changesets = await getChangesets(cwd); +``` + +This returns an array of formatted changesets. diff --git a/site/lib/release-utils.md b/site/lib/release-utils.md new file mode 100644 index 000000000..231272320 --- /dev/null +++ b/site/lib/release-utils.md @@ -0,0 +1 @@ +# @changesets/release-utils diff --git a/site/lib/should-skip-package.md b/site/lib/should-skip-package.md new file mode 100644 index 000000000..c7446a24d --- /dev/null +++ b/site/lib/should-skip-package.md @@ -0,0 +1 @@ +# @changesets/should-skip-package diff --git a/site/lib/types.md b/site/lib/types.md new file mode 100644 index 000000000..3df476cac --- /dev/null +++ b/site/lib/types.md @@ -0,0 +1,21 @@ +# @changesets/types + +[![npm package](https://img.shields.io/npm/v/@changesets/types)](https://npmjs.com/package/@changesets/types) + +[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" + +A package of types for use in changesets, or projects wishing to extend them. + +Of these, the most useful types are: + +## NewChangeset + +The format for a changeset as of changesets version 2. + +## ChangelogFunctions + +The shape of the object used for generating changelog entries. + +## ReleasePlan + +The combined object used to version packages and update changelogs. diff --git a/site/lib/write.md b/site/lib/write.md new file mode 100644 index 000000000..850357cc7 --- /dev/null +++ b/site/lib/write.md @@ -0,0 +1,43 @@ +# @changesets/write + +Writes a changeset to a file. + +```js +import write from "@changesets/write"; + +const changeset = { + summary: "A description of a minor change", + releases: [ + { name: "@changesets/something", type: "minor" }, + { name: "@changesets/something-else", type: "patch" }, + ], +}; + +const uniqueId = await write(changeset, cwd); +console.log(uniqueId); // orange-foxes-waggle +``` + +For example, it can convert: + +```json +{ + "summary": "A description of a minor change", + "releases": [ + { "name": "@changesets/something", "type": "minor" }, + { "name": "@changesets/something-else", "type": "patch" } + ] +} +``` + +to + +```markdown +--- +"@changesets/something": minor +"@changesets/something-else": patch +--- + +A description of a minor change +``` + +This package will take care of generating a unique id for the changeset. diff --git a/site/package.json b/site/package.json new file mode 100644 index 000000000..d3fce80a6 --- /dev/null +++ b/site/package.json @@ -0,0 +1,15 @@ +{ + "name": "@changesets/docs", + "private": true, + "version": "0.0.1", + "description": "The official documentation for Changesets", + "type": "module", + "scripts": { + "dev": "vitepress dev", + "build": "vitepress build", + "preview": "vitepress preview" + }, + "devDependencies": { + "vitepress": "^2.0.0-alpha.17" + } +} diff --git a/site/public/logo.svg b/site/public/logo.svg new file mode 100644 index 000000000..243072997 --- /dev/null +++ b/site/public/logo.svg @@ -0,0 +1,30 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/site/tsconfig.json b/site/tsconfig.json new file mode 100644 index 000000000..9bd010b02 --- /dev/null +++ b/site/tsconfig.json @@ -0,0 +1,14 @@ +{ + "compilerOptions": { + "target": "esnext", + "module": "esnext", + "moduleResolution": "bundler", + "allowImportingTsExtensions": true, + "erasableSyntaxOnly": true, + "libReplacement": false, + "strict": true, + "noEmit": true, + "types": ["vitepress/client"] + }, + "include": ["src/**/*", ".vitepress/**/*"] +} From 20b2d7fca450188ac2ff41ce9642d8f42eea5e3c Mon Sep 17 00:00:00 2001 From: bluwy Date: Tue, 5 May 2026 11:21:51 +0800 Subject: [PATCH 02/80] Update docs --- pnpm-lock.yaml | 226 +++++++++++++++++- site/faq/common-questions.md | 30 +++ site/guide/advance/decisions.md | 60 +++++ site/guide/advance/experimental-options.md | 17 ++ .../{pre-releases.md => prereleases.md} | 12 +- site/guide/advance/snapshot-releases.md | 4 +- site/guide/advance/versioning-apps.md | 16 +- site/guide/api/cli.md | 77 +++--- site/guide/basic/adding-a-changeset.md | 10 +- site/guide/basic/checking-for-changesets.md | 6 +- site/guide/basic/configuration.md | 166 +++++++------ site/guide/intro/concepts.md | 10 +- site/guide/intro/dictionary.md | 10 +- site/guide/intro/getting-started.md | 33 +-- site/guide/intro/what-are-changesets.md | 2 + site/lib/apply-release-plan.md | 27 --- site/lib/assemble-release-plan.md | 44 ---- site/lib/changelog-git.md | 1 - site/lib/changelog-github.md | 1 - site/lib/cli.md | 198 --------------- site/lib/config.md | 25 -- site/lib/errors.md | 7 - site/lib/get-dependents-graph.md | 16 -- site/lib/get-github-info.md | 85 ------- site/lib/get-release-plan.md | 26 -- site/lib/get-version-range-type.md | 10 - site/lib/git.md | 9 - site/lib/logger.md | 44 ---- site/lib/parse.md | 47 ---- site/lib/pre.md | 32 --- site/lib/read.md | 15 -- site/lib/release-utils.md | 1 - site/lib/should-skip-package.md | 1 - site/lib/types.md | 21 -- site/lib/write.md | 43 ---- site/package.json | 1 + 36 files changed, 516 insertions(+), 817 deletions(-) create mode 100644 site/faq/common-questions.md create mode 100644 site/guide/advance/decisions.md create mode 100644 site/guide/advance/experimental-options.md rename site/guide/advance/{pre-releases.md => prereleases.md} (85%) delete mode 100644 site/lib/apply-release-plan.md delete mode 100644 site/lib/assemble-release-plan.md delete mode 100644 site/lib/changelog-git.md delete mode 100644 site/lib/changelog-github.md delete mode 100644 site/lib/cli.md delete mode 100644 site/lib/config.md delete mode 100644 site/lib/errors.md delete mode 100644 site/lib/get-dependents-graph.md delete mode 100644 site/lib/get-github-info.md delete mode 100644 site/lib/get-release-plan.md delete mode 100644 site/lib/get-version-range-type.md delete mode 100644 site/lib/git.md delete mode 100644 site/lib/logger.md delete mode 100644 site/lib/parse.md delete mode 100644 site/lib/pre.md delete mode 100644 site/lib/read.md delete mode 100644 site/lib/release-utils.md delete mode 100644 site/lib/should-skip-package.md delete mode 100644 site/lib/types.md delete mode 100644 site/lib/write.md diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index dc7e84de1..aa94292e4 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -534,9 +534,12 @@ importers: site: devDependencies: + oxc-minify: + specifier: ^0.128.0 + version: 0.128.0 vitepress: specifier: ^2.0.0-alpha.17 - version: 2.0.0-alpha.17(@types/node@24.12.2)(postcss@8.5.13)(terser@5.44.1)(typescript@6.0.3) + version: 2.0.0-alpha.17(@types/node@24.12.2)(oxc-minify@0.128.0)(postcss@8.5.13)(terser@5.44.1)(typescript@6.0.3) packages: @@ -1222,6 +1225,133 @@ packages: '@open-draft/until@2.1.0': resolution: {integrity: sha512-U69T3ItWHvLwGg5eJ0n3I62nWuE6ilHlmz7zM0npLBRvPRd7e6NYmg54vvRtP5mZG7kZqZCFVdsTWo7BPtBujg==} + '@oxc-minify/binding-android-arm-eabi@0.128.0': + resolution: {integrity: sha512-EwdDhZLRmXxSnfy0v9gdOru7TutM8ItRg1Xv8e2B4boWMnHlFCIH38JfwgQnenbkF8SVTwVJtDCkmwEzN4q3xA==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [arm] + os: [android] + + '@oxc-minify/binding-android-arm64@0.128.0': + resolution: {integrity: sha512-kwJ8YxWTzty8hD36jXxKiB+Po/ecmHZvT1xAYklkATbr0A4NUqV32sV+3Wfm8TecdA6jX34/mc+4CKK2+Hha2Q==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [arm64] + os: [android] + + '@oxc-minify/binding-darwin-arm64@0.128.0': + resolution: {integrity: sha512-WBV8j5EZ7/3rvFbiJ8LxowmobR/XH+l2iRzkE7zRYLD5VC+TvZayYGrVGGDXQvXm6cGED0B1NweByTmeT4lpGQ==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [arm64] + os: [darwin] + + '@oxc-minify/binding-darwin-x64@0.128.0': + resolution: {integrity: sha512-U4k1CSBsY1uf6yHE+vCNJp0mHzjsUUXgOZXMyhRN3sE2ovBDT9Gl8oACmLWPjg0R68jwP+1vhnNPsSqpTEOycg==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [x64] + os: [darwin] + + '@oxc-minify/binding-freebsd-x64@0.128.0': + resolution: {integrity: sha512-NT1GtcWpX4sOuU5dMdSNpdXJRpk9BGAHHnKc42IUId8E+jEhZUrg9vqIRIlspZG5O9Y7FjO2r6GBK93bpyIIUg==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [x64] + os: [freebsd] + + '@oxc-minify/binding-linux-arm-gnueabihf@0.128.0': + resolution: {integrity: sha512-OskPMYMH2KtkqvRMULF2/+55hFo/qmRz2p/g7Cp7XNiqdjZ/DvQDiVbME63rVoX3dYjgS15DolGbo54mHTyA9w==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [arm] + os: [linux] + + '@oxc-minify/binding-linux-arm-musleabihf@0.128.0': + resolution: {integrity: sha512-fKUY7Y1vb8CYlGnS5FzqTeeM5zQz1Fleyaqz/T9iNHYAYNJ0Os9iT0rACLfAVCQKP9yOqPSwZ80xgZdVVGD61w==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [arm] + os: [linux] + + '@oxc-minify/binding-linux-arm64-gnu@0.128.0': + resolution: {integrity: sha512-T+CQQZ3BoWY/TxQk9LZsXZYj3madR/5tCErV6wzphTYZJfVjvKmQxnxMaT+TKE40Jha6+iGgwzxwcYWJfltULQ==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [arm64] + os: [linux] + libc: [glibc] + + '@oxc-minify/binding-linux-arm64-musl@0.128.0': + resolution: {integrity: sha512-F6RkJ90S1Xt25Mk7/wPUmddsE4RZ7Nei+HlEa2FAjfhpoaTciOwV6E/Gtp7wPIYbwft7UfhMYwuEuZiZQytVWw==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [arm64] + os: [linux] + libc: [musl] + + '@oxc-minify/binding-linux-ppc64-gnu@0.128.0': + resolution: {integrity: sha512-0HP2FBGMlquLjShIIJvS4cebc6sdRRYL04GtxVpg96MtpejrkHYI2gQWcezsTUaGgg+eNRsuv2tdZPENu5+iWA==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [ppc64] + os: [linux] + libc: [glibc] + + '@oxc-minify/binding-linux-riscv64-gnu@0.128.0': + resolution: {integrity: sha512-2j6Bd340IZqZbu4KUI28z87Ao9aHhq56HH1Qz5/+EdE732ajFYIoDF3z+QcxHXY0CFOG/Ur1ZOKTBEIWQ6BYIw==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [riscv64] + os: [linux] + libc: [glibc] + + '@oxc-minify/binding-linux-riscv64-musl@0.128.0': + resolution: {integrity: sha512-z5HSppdxNwB6//3Eo7mDWbTrLeyuTKvL/iLXaKEgocrJg1MhZLbRR7P5ore9gKvS4lF4EtEpA24xzilFxQK0iw==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [riscv64] + os: [linux] + libc: [musl] + + '@oxc-minify/binding-linux-s390x-gnu@0.128.0': + resolution: {integrity: sha512-9rxYqH7P8NiYqRlLxlnNjJSF8BYADOmihM5ZHVkmlE4tqjHkoLNevdAyAP2ZBkL8QJflm1WGOXFWmFnWA54EvA==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [s390x] + os: [linux] + libc: [glibc] + + '@oxc-minify/binding-linux-x64-gnu@0.128.0': + resolution: {integrity: sha512-sy5+4Oamw6Ly5gUNUIDQ7346Lryt7AhqjKhOtWl5dzYZnTIwwoI0V2DeIl3bR/vU8D629ZMYQOqhquRtSyBUOA==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [x64] + os: [linux] + libc: [glibc] + + '@oxc-minify/binding-linux-x64-musl@0.128.0': + resolution: {integrity: sha512-59Cxvjppy09TsaB15gr6rA9Bf87rm9t0bD1EW9dCZsdxWElnAC+TvWZ7v9dFUIeYeZUkhAAMPtpdqa3Y9CI2zA==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [x64] + os: [linux] + libc: [musl] + + '@oxc-minify/binding-openharmony-arm64@0.128.0': + resolution: {integrity: sha512-XGa03zmiYpD7Kf1aXy6vjgkjfaCR90qH0TzGplnUXo6FF6gNe6sH9Zgneo9kxOyYt8CKKzXYD4VudT/nDTXq8Q==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [arm64] + os: [openharmony] + + '@oxc-minify/binding-wasm32-wasi@0.128.0': + resolution: {integrity: sha512-W+fK3cWhu/cUgx3NIAmDYcAyJs01aULlr3E3n/ZN79Q1/CX+FS+yWfwt/IysIi4FhpVL7z58azbJHDzhEx4X4g==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [wasm32] + + '@oxc-minify/binding-win32-arm64-msvc@0.128.0': + resolution: {integrity: sha512-pwMZd27FF+j4tHLYKtu4QBl6KI0gkt6xTNGLffs8VlH5vfDPHUvLo/AS6y66tdEjQ3chhs8OGg1mAFhPoQldDw==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [arm64] + os: [win32] + + '@oxc-minify/binding-win32-ia32-msvc@0.128.0': + resolution: {integrity: sha512-GskPdx/Fsn3ttkJbzxh51LYhla4N4p1sMufJKgf6PHupt5RukBaHI/GKM/2ni6ObxUI0b9UK37fROdV+5ekpMQ==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [ia32] + os: [win32] + + '@oxc-minify/binding-win32-x64-msvc@0.128.0': + resolution: {integrity: sha512-m8oakspZCbCod3WuY0U9DvwQlhMYaU31bK+Way1Rb+JGs455WLtkebEie/luSuN5DeF+aZyRH/zt1AY4weKQQg==} + engines: {node: ^20.19.0 || >=22.12.0} + cpu: [x64] + os: [win32] + '@oxc-project/types@0.127.0': resolution: {integrity: sha512-aIYXQBo4lCbO4z0R3FHeucQHpF46l2LbMdxRvqvuRuW2OxdnSkcng5B8+K12spgLDj93rtN3+J2Vac/TIO+ciQ==} @@ -2552,6 +2682,10 @@ packages: outvariant@1.4.3: resolution: {integrity: sha512-+Sl2UErvtsoajRDKCE5/dBz4DIvHXQQnAxtQTF04OJxY0+DyZXSo5P5Bb7XYWOh81syohlYL24hbDwxedPUJCA==} + oxc-minify@0.128.0: + resolution: {integrity: sha512-VIXQO2W886aB+N17yV55Sack6aCpbUqtuNAYhNcPV6dFiWIZ5+kwOjvvw36igWwoljfjWhasu99CQ5wtvPJDYg==} + engines: {node: ^20.19.0 || >=22.12.0} + p-limit@3.1.0: resolution: {integrity: sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==} engines: {node: '>=10'} @@ -3935,6 +4069,70 @@ snapshots: '@open-draft/until@2.1.0': {} + '@oxc-minify/binding-android-arm-eabi@0.128.0': + optional: true + + '@oxc-minify/binding-android-arm64@0.128.0': + optional: true + + '@oxc-minify/binding-darwin-arm64@0.128.0': + optional: true + + '@oxc-minify/binding-darwin-x64@0.128.0': + optional: true + + '@oxc-minify/binding-freebsd-x64@0.128.0': + optional: true + + '@oxc-minify/binding-linux-arm-gnueabihf@0.128.0': + optional: true + + '@oxc-minify/binding-linux-arm-musleabihf@0.128.0': + optional: true + + '@oxc-minify/binding-linux-arm64-gnu@0.128.0': + optional: true + + '@oxc-minify/binding-linux-arm64-musl@0.128.0': + optional: true + + '@oxc-minify/binding-linux-ppc64-gnu@0.128.0': + optional: true + + '@oxc-minify/binding-linux-riscv64-gnu@0.128.0': + optional: true + + '@oxc-minify/binding-linux-riscv64-musl@0.128.0': + optional: true + + '@oxc-minify/binding-linux-s390x-gnu@0.128.0': + optional: true + + '@oxc-minify/binding-linux-x64-gnu@0.128.0': + optional: true + + '@oxc-minify/binding-linux-x64-musl@0.128.0': + optional: true + + '@oxc-minify/binding-openharmony-arm64@0.128.0': + optional: true + + '@oxc-minify/binding-wasm32-wasi@0.128.0': + dependencies: + '@emnapi/core': 1.10.0 + '@emnapi/runtime': 1.10.0 + '@napi-rs/wasm-runtime': 1.1.4(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0) + optional: true + + '@oxc-minify/binding-win32-arm64-msvc@0.128.0': + optional: true + + '@oxc-minify/binding-win32-ia32-msvc@0.128.0': + optional: true + + '@oxc-minify/binding-win32-x64-msvc@0.128.0': + optional: true + '@oxc-project/types@0.127.0': {} '@pnpm/config.env-replace@1.1.0': {} @@ -5358,6 +5556,29 @@ snapshots: outvariant@1.4.3: {} + oxc-minify@0.128.0: + optionalDependencies: + '@oxc-minify/binding-android-arm-eabi': 0.128.0 + '@oxc-minify/binding-android-arm64': 0.128.0 + '@oxc-minify/binding-darwin-arm64': 0.128.0 + '@oxc-minify/binding-darwin-x64': 0.128.0 + '@oxc-minify/binding-freebsd-x64': 0.128.0 + '@oxc-minify/binding-linux-arm-gnueabihf': 0.128.0 + '@oxc-minify/binding-linux-arm-musleabihf': 0.128.0 + '@oxc-minify/binding-linux-arm64-gnu': 0.128.0 + '@oxc-minify/binding-linux-arm64-musl': 0.128.0 + '@oxc-minify/binding-linux-ppc64-gnu': 0.128.0 + '@oxc-minify/binding-linux-riscv64-gnu': 0.128.0 + '@oxc-minify/binding-linux-riscv64-musl': 0.128.0 + '@oxc-minify/binding-linux-s390x-gnu': 0.128.0 + '@oxc-minify/binding-linux-x64-gnu': 0.128.0 + '@oxc-minify/binding-linux-x64-musl': 0.128.0 + '@oxc-minify/binding-openharmony-arm64': 0.128.0 + '@oxc-minify/binding-wasm32-wasi': 0.128.0 + '@oxc-minify/binding-win32-arm64-msvc': 0.128.0 + '@oxc-minify/binding-win32-ia32-msvc': 0.128.0 + '@oxc-minify/binding-win32-x64-msvc': 0.128.0 + p-limit@3.1.0: dependencies: yocto-queue: 0.1.0 @@ -5727,7 +5948,7 @@ snapshots: fsevents: 2.3.3 terser: 5.44.1 - vitepress@2.0.0-alpha.17(@types/node@24.12.2)(postcss@8.5.13)(terser@5.44.1)(typescript@6.0.3): + vitepress@2.0.0-alpha.17(@types/node@24.12.2)(oxc-minify@0.128.0)(postcss@8.5.13)(terser@5.44.1)(typescript@6.0.3): dependencies: '@docsearch/css': 4.6.3 '@docsearch/js': 4.6.3 @@ -5749,6 +5970,7 @@ snapshots: vite: 8.0.10(@types/node@24.12.2)(terser@5.44.1) vue: 3.5.33(typescript@6.0.3) optionalDependencies: + oxc-minify: 0.128.0 postcss: 8.5.13 transitivePeerDependencies: - '@types/node' diff --git a/site/faq/common-questions.md b/site/faq/common-questions.md new file mode 100644 index 000000000..d2e719a15 --- /dev/null +++ b/site/faq/common-questions.md @@ -0,0 +1,30 @@ +# Common Questions + +A quick list of common questions you might want answered to understand what changesets is doing, without going into minutiae or workflow. + +## Changesets are automatically generated + +Changesets are generated by the `yarn changeset` or `npx @changesets/cli` command. As long as you are following a changeset release flow, you shouldn't have any problems. + +## Each changeset is its own file + +We use random human readable names by default for these files to avoid collisions when generating them, but there's no harm that will come from renaming them. + +## Changesets are automatically removed + +When `changeset version` or equivalent command is run, all the changeset files are removed. This is so we only ever use a changeset once. This makes the `.changeset` folder a very bad place to store any other information. + +## Changesets are markdown files with YAML front matter + +The two parts of the file are for different purposes. You should feel free to edit both parts as much as you want. + +- The markdown text is a summary of the changes that will be prepended to your changelog when you next run your version command. +- The YAML front matter describes what should be versioned by the version command + +## I want to edit the summary or package bump types - is it safe to do that? + +Editing the summary or package bump types is completely safe. You can even write changesets without the command if you want. + +## Can I manually delete changesets? + +You can, but you should be aware this will remove the intent to release communicated by the changeset, and should be done with caution. diff --git a/site/guide/advance/decisions.md b/site/guide/advance/decisions.md new file mode 100644 index 000000000..bddc29e24 --- /dev/null +++ b/site/guide/advance/decisions.md @@ -0,0 +1,60 @@ +# Decisions + +This file is a discussion of some of the rules and design decisions that have gone into making changesets. The goal of all of these has been to make the experience of using changesets easy, while still providing the maximum value possible. + +## How changesets are combined + +Changesets are designed to be as easy to accumulate as possible. As such, when changesets are consumed with `version`, we flatten the version bumps into one single bump at the highest semver range specified. + +For example: if you run `version`, and we have `packageA` at `1.1.1`, which has two `minor` changesets, and one `patch` changeset, we will bump `packageA` to `1.2.0`. + +This allows changesets to be added and accumulated safely, with the knowledge that packages will only be released once at an appropriate version for the combined set of changesets, while still ensuring each change is captured in the changelog, with an indication of what kind of change it is. + +## How dependencies are bumped + +> NOTE: This refers specifically to a feature of changesets used in mono-repos + +When changesets are generated, we check to see if the selected packages will leave semver for any other packages within the mono-repo. + +For example, if I have two packages: + +`packageA` at `1.1.1` + +and `packageB` at `1.1.0` that depends on `packageA` at `^1.1.0`. + +If I add `packageA` to a changeset with a `major` change, the version of `packageB` within the mono-repo should also be updated. If it is not, either `packageB` in the mono-repo will not use `packageA` in development, or `packageB` in development will not match an installation of `packageB` in production. + +As such we end up with a changeset that includes `packageA` as `major` and `packageB` as `patch`. + +All updating of dependencies is done as a patch bump. If you want to indicate a more significant change to `packageB` from consuming a new version of `packageA`, we recommend adding a second changeset specifically for `packageB`. + +## Why do we write files to disc + +There are two reasons we chose to do this. The first is so the changeset descriptions are editable after creation, and a user can go in and change this as they desire. The second is that it means we are unopinionated about your git workflows, with squashing and modifying commits being completely safe, without fear of breaking a release. + +## What distinguishes this from Semantic Release + +If you have been looking at automating versioning previously, you may have come across [semantic release](https://github.com/semantic-release/semantic-release), or its mono-repo equivalent [lerna semantic release](https://github.com/atlassian/lerna-semantic-release). It's good to understand how changesets operate differently. + +1. Changesets are designed for mono-repos first. + +This means we manage dependencies within the repository, which other tools do not do. + +2. We commit our change information to the file system, instead of storing it in git. + +See the above section on why we write files to disc. + +3. We use semver for specifying the change. + +When selecting the kind of change your package is, we do not specify any change types beyond `major`, `minor`, or `patch`. The semantic release allows you to specify a range of fields (bug-fix, feature) that it converts to an appropriate semver type. This is a design decision on our part to push adding this information into the changeset description itself. + +## The versioning of peer dependencies + +Currently, if you list a package as a `peerDependency` of another package, this causes the package with the `peerDependency` to +be released as a `major` change. This is because `peerDependency` changes will not be caught by a package installation. + +This decision is open for discussion. + +## How Changesets interacts with Git + +Changesets core flow of adding changesets, versioning packages/writing changelogs, and publishing packages should work without Git. Using Git in a way where the user doesn't explicitly ask to do something that involves Git such as showing changed packages in the add command shouldn't show an error if Git fails for any reason. Using Git in a way where the user explicitly chooses to use Git such as using the commit option or `status --since main`, Changesets should log an error and fail with a non-zero exit code. diff --git a/site/guide/advance/experimental-options.md b/site/guide/advance/experimental-options.md new file mode 100644 index 000000000..9eb163949 --- /dev/null +++ b/site/guide/advance/experimental-options.md @@ -0,0 +1,17 @@ +# Experimental Options + +All experimental options are configured in `config.json` under `___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH` flag. + +> Please use these experimental flags with caution, and please pay attention to release notes - these config flags might change in patch versions. + +## `updateInternalDependents` (type: `'out-of-range' | 'always'`) + +Default value: `out-of-range`. + +The config flag can be used to add dependent packages to the release (if they are not already a part of it) with patch bumps. + +## `onlyUpdatePeerDependentsWhenOutOfRange` (type: `boolean`) + +Default value: `false` + +When set to `true`, Changesets will only bump peer dependents when `peerDependencies` are leaving the range. diff --git a/site/guide/advance/pre-releases.md b/site/guide/advance/prereleases.md similarity index 85% rename from site/guide/advance/pre-releases.md rename to site/guide/advance/prereleases.md index 023879159..d53649b22 100644 --- a/site/guide/advance/pre-releases.md +++ b/site/guide/advance/prereleases.md @@ -1,10 +1,10 @@ # Prereleases > [!WARNING] -> Pre releases are very complicated! Using them requires a thorough understanding of all parts of npm publishes. Mistakes can lead to repository and publish states that are very hard to fix. +> Prereleases are very complicated! Using them requires a thorough understanding of all parts of npm publishes. Mistakes can lead to repository and publish states that are very hard to fix. > [!WARNING] -> If you decide to do prerelease from the main branch of your repository, without having a branch for your last stable release without the prerelease changes, you will block other changes until you are ready to exit prerelease mode. We thoroughly recommend only running prerelease from a branch other than the main branch. +> If you decide to do prereleases from the default branch of your repository, without having a branch for your last stable release without the prerelease changes, you will block other changes until you are ready to exit prerelease mode. We thoroughly recommend only running prereleases from a branch other than the default branch. You might want to release a version of your packages before you do an actual release, Changesets lets you do this but there are some caveats because of the complexity that monorepos add that are important to understand. @@ -48,7 +48,7 @@ The repo would now look like this: ``` packages/ - pkg-a@1.0.1-next.0 has dep on pkg-b@^2.0.1 + pkg-a@1.0.1-next.0 has dep on pkg-b@^2.1.0-next.0 pkg-b@2.1.0-next.0 has no deps pkg-c@3.0.0 has no deps .changeset/ @@ -74,7 +74,7 @@ Let's say we add some changesets and a new package so our repo looks like this ``` packages/ - pkg-a@1.0.1-next.0 has dep on pkg-b@^2.0.1 + pkg-a@1.0.1-next.0 has dep on pkg-b@^2.1.0-next.0 pkg-b@2.1.0-next.0 has no deps pkg-c@3.0.0 has no deps pkg-d@0.0.0 has no deps @@ -93,7 +93,7 @@ The version command will behave just like it does for the first versioning of a ``` packages/ - pkg-a@1.1.0-next.1 has dep on pkg-b@^2.0.1 + pkg-a@1.1.0-next.1 has dep on pkg-b@^2.1.0-next.0 pkg-b@2.1.0-next.0 has no deps pkg-c@3.0.1-next.0 has no deps pkg-d@1.0.0-next.0 has no deps @@ -130,7 +130,7 @@ The version command will apply any changesets currently in the repo and then rem ``` packages/ - pkg-a@1.1.0 has dep on pkg-b@^2.0.1 + pkg-a@1.1.0 has dep on pkg-b@^2.1.0 pkg-b@2.1.0 has no deps pkg-c@3.0.1 has no deps pkg-d@1.0.0 has no deps diff --git a/site/guide/advance/snapshot-releases.md b/site/guide/advance/snapshot-releases.md index 12239d184..6c5ada30d 100644 --- a/site/guide/advance/snapshot-releases.md +++ b/site/guide/advance/snapshot-releases.md @@ -4,7 +4,7 @@ Snapshot releases are a way to release your changes for testing without updating ## Starting Off -Create changesets as normal, as described in [adding a changeset](/guide/basic/adding-a-changeset). When you are ready to release a snapshot, you should make a dedicated branch for doing so. +Create changesets as normal, as described in [adding a changeset](../../guide/basic/adding-a-changeset.md). When you are ready to release a snapshot, you should make a dedicated branch for doing so. ## Versioning your packages @@ -30,7 +30,7 @@ After running the `yarn changeset version` command, you can use the `changeset p You can use the `--no-git-tag` CLI flag when running `changeset publish` if you plan to publish snapshot releases locally or you are pushing [git tags](http://npm.github.io/publishing-pkgs-docs/updating/using-tags.html) to a remote from your CI environment. -When you run `changeset publish --no-git-tag --snapshot`, changesets will skip creating git tags for published snapshot packages. That means that git tags can still be created whenever pushing stable versions (with a regular `changeset publish`), and you can safely publish snapshot releases locally, without creating unnecessary tags. +When you run `changeset publish --no-git-tag`, changesets will skip creating git tags for published snapshot packages. That means that git tags can still be created whenever pushing stable versions (with a regular `changeset publish`), and you can safely publish snapshot releases locally, without creating unnecessary tags. ## Using a snapshot version diff --git a/site/guide/advance/versioning-apps.md b/site/guide/advance/versioning-apps.md index b553e9bd5..da7fb11f1 100644 --- a/site/guide/advance/versioning-apps.md +++ b/site/guide/advance/versioning-apps.md @@ -1,4 +1,4 @@ -# Managing Applications or Non-npm Packages +# Managing applications or non-npm packages Changesets can also be used to manage application versions or non-npm packages (ie dotnet NuGet packages, ruby gems, docker images etc). @@ -20,3 +20,17 @@ To enable a project to be tracked by changesets, it needs a minimal package.json "version": "0.0.1" } ``` + +## Private dependencies + +When a versioned private package (app) depends on another private package that is skipped (either via the `ignore` option or `privatePackages.version: false`), changesets will not require the app to also be skipped. Since private packages are not published to npm, it is safe for them to depend on skipped packages. + +For example, if you have an app `A` that depends on a private library `B`, you can ignore `B` while still versioning `A`: + +```json +{ + "ignore": ["B"] +} +``` + +This works because `A` is private and will never be published to npm with a stale reference to `B`. diff --git a/site/guide/api/cli.md b/site/guide/api/cli.md index 1eb74175d..1bb036610 100644 --- a/site/guide/api/cli.md +++ b/site/guide/api/cli.md @@ -1,34 +1,34 @@ # Command line options -The command line for changesets is the main way of interacting with it. There are 4 main commands. If you are looking for how we recommend you setup and manage changesets with the commands, check out our [intro to using changesets](/guide/intro/getting-started) +The command line for changesets is the main way of interacting with it. There are 4 main commands. If you are looking for how we recommend you setup and manage changesets with the commands, check out our [intro to using changesets](../intro/getting-started.md) -- init -- add [--empty][--open] -- version [--ignore, --snapshot] -- publish [--otp=code, --tag] -- status [--since=master --verbose --output=JSON_FILE.json] -- pre [exit|enter {tag}] -- tag +- `init` +- `add [--empty] [--open] [--since ] [--message ]` +- `version [--ignore, --snapshot]` +- `publish [--otp=code, --tag]` +- `status [--since=master --verbose --output=JSON_FILE.json]` +- `pre [exit|enter {tag}]` +- `tag` The most important commands are `add`, which is used by contributors to add information about their changes, `version` - which is responsible for using the changesets generated by `add` to update package versions and changelogs, and then `publish` which publishes changes to npm. ## `init` -```bash +``` changeset init ``` -This command sets up the .changeset folder. It generates a readme and a config file. The config file includes the default options and comments on what these options represent. You should run this command once when you are setting up changesets. +This command sets up the `.changeset` folder. It generates a readme and a config file. The config file includes the default options and comments on what these options represent. You should run this command once when you are setting up changesets. ## `add` -```bash +``` changeset add ``` or just -```bash +``` changeset ``` @@ -36,11 +36,11 @@ This is the main command people use to interact with the changesets. This command will ask you a series of questions, first about what packages you want to release, then what semver bump type for each package, then it will ask for a summary of the entire changeset. The final step will show the changeset it will generate and confirm that you want to add it. -Once confirmed, the changeset will be written a Markdown file that contains the summary and YAML front matter which stores the packages that will be released and the semver bump types for them. +Once confirmed, the changeset will be written as a Markdown file that contains the summary and YAML front matter which stores the packages that will be released and the semver bump types for them. -A changeset that major bumps @changesets/cli would look like this: +A changeset that major bumps `@changesets/cli` would look like this: -```md +``` --- "@changesets/cli": major --- @@ -51,13 +51,13 @@ If you want to modify this file after it's generated, that's completely fine or - `--empty` - allows you to create an empty changeset if no packages are being bumped, usually only required if you have CI that blocks merges without a changeset. -```bash +``` changeset --empty ``` A changeset created with the empty flag would look like this: -```md +``` --- --- ``` @@ -65,21 +65,27 @@ A changeset created with the empty flag would look like this: If you set the commit option in the config, the command will add the updated changeset files and then commit them. - `--open` - opens the created changeset in an external editor +- `--message` (or `-m`) - provides the changeset summary from the command line instead of prompting for it. + +- `--since` - uses the provided branch, tag, or git ref (such as `main` or a git commit hash) to detect which packages have changed when populating the list of changed packages in the CLI. This is useful in gitflow workflows where you have multiple target branches and `baseBranch` in the config doesn't cover all use cases. If not provided, the command falls back to the `baseBranch` value in your `.changeset/config.json`. + +``` +changeset add --since=develop +``` ## version -```bash +``` changeset version ``` This is one of two commands responsible for releasing packages. The version command takes changesets that have been made and updates versions and dependencies of packages, as well as writing changelogs. It is responsible for all file changes to versions before publishing to npm. -> [!TIP] > We recommend making sure changes made from this command are merged back into the base branch before you run publish. Version has two options, `ignore` and `snapshot`: -```bash +``` changeset version --ignore PACKAGE_NAME ``` @@ -88,17 +94,17 @@ This command is used to allow you to skip packages from being published. This al 1. If the package is mentioned in a changeset that also includes a package that is not ignored, publishing will fail. 2. If the package requires one of its dependencies to be updated as part of a publish. -These restrictions exist to ensure your repository or published code does not end up in a broken state. For additional information on the intricacies of publishing, check out our guide on [problems publishing in monorepos](/faq/publishing-in-monorepos). +These restrictions exist to ensure your repository or published code does not end up in a broken state. For additional information on the intricacies of publishing, check out our guide on [problems publishing in monorepos](../../faq/publishing-in-monorepos.md). -```bash +``` changeset version --snapshot ``` -Snapshot is used for a special kind of publishing for testing - it creates temporary versions with a tag, instead of updating versions from the current semver ranges. You should not use this without [reading the documentation on snapshot releases](/guide/advance/snapshot-releases) +Snapshot is used for a special kind of publishing for testing - it creates temporary versions with a tag, instead of updating versions from the current semver ranges. You should not use this without [reading the documentation on snapshot releases](../advance/snapshot-releases.md) ## publish -```bash +``` changeset publish [--otp={token}] ``` @@ -108,20 +114,20 @@ Because this command assumes that the last commit is the release commit, you sho `--otp={token}` - allows you to provide an npm one-time password if you have auth and writes enabled on npm. The CLI also prompts for the OTP if it's not provided with the --otp option. -`--tag TAGNAME` - for packages that are published, the chosen tag will be used instead of `latest`, allowing you to publish changes intended for testing and validation, not main consumption. This will most likely be used with [snapshot releases](/guide/advance/snapshot-releases). +`--tag TAGNAME` - for packages that are published, the chosen tag will be used instead of `latest`, allowing you to publish changes intended for testing and validation, not main consumption. This will most likely be used with [snapshot releases](../advance/snapshot-releases.md). ### Git Tags It is useful to have git tags of a publish, to allow people looking for the code at that time to find them. We generate tags in git during publish, but you will need to push them back up if you want to make them available. We recommend after publish you run: -```bash +``` git push --follow-tags ``` ## status -```bash -status [--verbose] [--output={filePath}] [--since={gitTag}] +``` +changeset status [--verbose] [--output={filePath}] [--since={gitTag}] ``` The status command provides information about the changesets that currently exist. If there are no changesets present, it exits with an error status code. @@ -132,23 +138,22 @@ The status command provides information about the changesets that currently exis - `--since` - to only display information about changesets since a specific branch or git tag (such as `main`, or the git hash of latest). While this can be used to add a CI check for changesets, we recommend not doing this. We instead recommend using the [changeset bot](https://github.com/apps/changeset-bot) to detect pull requests missing changesets, as not all pull requests need one if you are on GitHub. -> [!NOTE] > `status` will fail if you are in the middle of running `version` or `publish`. If you want to get changeset status at the time of a version increase and publish, you need to run it immediately before running `version`. +> NOTE: `status` will fail if you are in the middle of running `version` or `publish`. If you want to get changeset status at the time of a version increase and publish, you need to run it immediately before running `version`. ## pre -```bash -pre [exit|enter {tag}] +``` +changeset pre [exit|enter {tag}] ``` -The pre command enters and exits pre mode. The command does not do any actual versioning, when doing a pre-release, you should run changeset pre enter next(or a different tag, the tag is what is in versions and is the npm dist tag) and then do the normal release process with changeset version and changeset publish. For more information about the pre command, see the prereleases [the prereleases documentation](/guide/advance/pre-releases). +The pre command enters and exits pre mode. The command does not do any actual versioning, when doing a pre-release, you should run changeset pre enter next(or a different tag, the tag is what is in versions and is the npm dist tag) and then do the normal release process with changeset version and changeset publish. For more information about the pre command, see the prereleases [the prereleases documentation](https://github.com/changesets/changesets/blob/master/docs/prereleases.md). -> [!CAUTION] -> pre-releases are a very complicated feature. Many of the safety rails that changesets helps you with will be taken off. We recommend that you read both [problems publishing in monorepos](/faq/publishing-in-monorepos) and be clear on both exiting and entering pre-releases before using it. You may also prefer using [snapshot releases](/guide/advance/snapshot-releases) for a slightly less involved process. +> NOTE: pre-releases are a very complicated feature. Many of the safety rails that changesets helps you with will be taken off. We recommend that you read both [problems publishing in monorepos](../../faq/publishing-in-monorepos.md) and be clear on both exiting and entering pre-releases before using it. You may also prefer using [snapshot releases](../advance/snapshot-releases.md) for a slightly less involved process. ## tag -```bash -tag +``` +changeset tag ``` The tag command creates git tags for the current version of all packages. The tags created are equivalent to those created by [`changeset publish`](#publish), but the `tag` command does not publish anything to npm. diff --git a/site/guide/basic/adding-a-changeset.md b/site/guide/basic/adding-a-changeset.md index 4922b882a..8108f45c3 100644 --- a/site/guide/basic/adding-a-changeset.md +++ b/site/guide/basic/adding-a-changeset.md @@ -1,4 +1,4 @@ -# Adding a Changeset +# Adding a changeset Hi! You might be here because a person or a bot has asked you to 'add a changeset' to a project. Let's walk through adding a changeset. But first, what is a changeset? @@ -12,7 +12,7 @@ A changeset is a piece of information about changes made in a branch or commit. ## I am in a multi-package repository (a mono-repo) -1. Run the command line script `npx changeset` or `yarn changeset`. +1. Run the command line script `yarn changeset` or `pnpm changeset` or `npx @changesets/cli`. 2. Select the packages you want to include in the changeset using ↑ and ↓ to navigate to packages, and space to select a package. Hit enter when all desired packages are selected. 3. You will be prompted to select a bump type for each selected package. Select an appropriate bump type for the changes made. See [here](https://semver.org/) for information on semver versioning 4. Your final prompt will be to provide a message to go alongside the changeset. This will be written into the changelog when the next release occurs. @@ -36,8 +36,8 @@ While not every changeset is going to need a huge amount of detail, a good idea ## I am in a single-package repository -1. Run the command line script `npx changeset` or `yarn changeset`. -2. Select an appropriate bump type for the changes made. See [here](https://semver.org/) for information on semver versioning +1. Run the command line script `yarn changeset` or `pnpm changeset` or `npx @changesets/cli`. +2. Select an appropriate bump type for the changes made. See [here](https://semver.org/) for information on semver versioning. 3. Your final prompt will be to provide a message to go alongside the changeset. This will be written into the changelog when the next release occurs. After this, a new changeset will be added which is a markdown file with YAML front matter. @@ -68,4 +68,4 @@ Changesets are designed to stack, so there's no problem with adding multiple. Yo ## I want to know more about changesets -[here is the concepts of changesets](/guide/intro/concepts) +[here is a more in-depth explanation](../intro/concepts.md) diff --git a/site/guide/basic/checking-for-changesets.md b/site/guide/basic/checking-for-changesets.md index 57eac139d..69082de5b 100644 --- a/site/guide/basic/checking-for-changesets.md +++ b/site/guide/basic/checking-for-changesets.md @@ -1,9 +1,7 @@ -# Checking for Changesets - -[//]: # "todo: replace the link below with a link to the docs" +# Checking for changesets Using `@changesets/cli`, there is a `status` command. See the docs for it in the -[@changesets/cli](/lib/cli#status) +[@changesets/cli readme](https://github.com/changesets/changesets/tree/main/packages/cli#status) We have a [github bot](https://github.com/apps/changeset-bot) and a [bitbucket addon](https://bitbucket.org/atlassian/atlaskit-mk-2/src/master/build/bitbucket-release-addon/) that diff --git a/site/guide/basic/configuration.md b/site/guide/basic/configuration.md index 356e3ea50..ff8dc363e 100644 --- a/site/guide/basic/configuration.md +++ b/site/guide/basic/configuration.md @@ -4,26 +4,25 @@ Changesets has a minimal amount of configuration options. Mostly these are for w ```json { + "changelog": "@changesets/cli/changelog", "commit": false, - "updateInternalDependencies": "patch", + "fixed": [], "linked": [], "access": "restricted", "baseBranch": "master", + "updateInternalDependencies": "patch", "ignore": [], - "changelog": "@changesets/cli/changelog" + "bumpVersionsWithWorkspaceProtocolOnly": false, + "changedFilePatterns": ["**"], + "prettier": true, + "privatePackages": { "version": true, "tag": false } } ``` > [!NOTE] > The `linked`, `fixed`, `updateInternalDependencies`, `bumpVersionsWithWorkspaceProtocolOnly`, and `ignore` options are only for behaviour in monorepos. -## `commit` - -> [!NOTE] Type: -> -> - `boolean` -> - `string`(module path) -> - a tuple like `[modulePath: string, options: any]` +## `commit` (`boolean`, or module path as a `string`, or a tuple like `[modulePath: string, options: any]`) This option is for setting if the `changeset add` command and the `changeset version` commands will also add and commit the changed files using git, and how the commit messages should be generated for them. @@ -46,14 +45,9 @@ You would specify a custom commit message generator with: } ``` -This is similar to how the [changelog generator functions work](#changelog). - -## `access` +This is similar to how the [changelog generator functions work](#changelog-false-or-a-path). -> [!NOTE] Type: -> -> - `restricted` -> - `public` +## `access` (`restricted` | `public`) This sets how packages are published - if `access: "restricted"`, packages will be published as private, requiring log in to an npm account with access to install. If `access: "public"`, the packages will be made available on the public registry. @@ -63,22 +57,15 @@ This can be overridden in specific packages by setting the `access` in a package If you want to prevent a package from being published to npm, set `private: true` in that package's `package.json` -## `baseBranch` +## `baseBranch` (git branch name) -> [!NOTE] Type: -> -> - `string` (git branch name) +The branch to which changesets will make comparisons to detect what has changed since the last commit of the base branch. This should generally be set to the default branch you merge changes into, e.g. `main` or `master`. -The branch to which changesets will make comparisons. A number of internal changesets features use git to compare present changesets against another branch. This defaults what branch will be used for these comparisons. This should generally set to the major branch you merge changes into. Commands that use this information accept a `--since` option which can be used to override this. +Commands that use this information accept a `--since` option which can be used to override this. -> [!TIP] -> To help make coding a more inclusive experience, we recommend changing the name of your `master` branch to `main`. - -## `ignore` +Locally, make sure the base branch exists and is up to date so changesets can make accurate comparisons. -> [!NOTE] Type: -> -> - `string[]` (names of packages) +## `ignore` (array of packages) This option allows you to specify some packages that will not be published, even if they are referenced in changesets. Instead, those changesets will be skipped until they are removed from this array. @@ -90,16 +77,12 @@ There are two caveats to this. 1. If the package is mentioned in a changeset that also includes a package that is not ignored, publishing will fail. 2. If the package requires one of its dependencies to be updated as part of a publish. -These restrictions exist to ensure your repository or published code do not end up in a broken state. For a more detailed intricacies of publishing, check out our guide on [problems publishing in monorepos](/faq/publishing-in-monorepos). +These restrictions exist to ensure your repository or published code do not end up in a broken state. For a more detailed intricacies of publishing, check out our guide on [problems publishing in monorepos](../../faq/publishing-in-monorepos.md). > [!TIP] > You can also provide glob expressions to match the packages, according to the [micromatch](https://www.npmjs.com/package/micromatch) format. -## `fixed` - -> [!NOTE] Type: -> -> - `string[][]` (array of arrays of package names) +## `fixed` (array of arrays of package names) This option can be used to declare that packages should be version-bumped and published together. As an example, if you have a `@changesets/button` component and a `@changesets/theme` component and you want to make sure that when one gets bumped to `1.1.0`, the other is also bumped to `1.1.0` regardless if it has any change or not. To achieve this you would have the config: @@ -109,13 +92,9 @@ This option can be used to declare that packages should be version-bumped and pu } ``` -If you want to use this option, you should read the documentation on [fixed packages](/guide/advance/fixed-packages) to fully understand the implementation and implications. +If you want to use this option, you should read the documentation on [fixed packages](../advance/fixed-packages.md) to fully understand the implementation and implications. -## `linked` - -> [!NOTE] Type: -> -> - `string[][]` (array of arrays of package names) +## `linked` (array of arrays of package names) This option can be used to declare that packages should 'share' a version, instead of being versioned completely independently. As an example, if you have a `@changesets/button` component and a `@changesets/theme` component and you want to make sure that when one gets bumped to `2.0.0`, the other is also bumped to `2.0.0`. To achieve this you would have the config: @@ -125,17 +104,12 @@ This option can be used to declare that packages should 'share' a version, inste } ``` -If you want to use this option, you should read the documentation on [linked packages](/guide/advance/linked-packages) to fully understand the implementation and implications. +If you want to use this option, you should read the documentation on [linked packages](../advance/linked-packages.md) to fully understand the implementation and implications. -> [!CAUTION] +> [!WARNING] > This does not do what some other tools do, which is make sure when any package is published, all other packages are also published with the same version. -## `updateInternalDependencies` - -> [!NOTE] Type: -> -> - `out-of-range` -> - `always` +## `updateInternalDependencies` This option sets whether, when a package that is being depended upon changes, whether you should update what version it depends on. To make this more understandable, here is an example: @@ -172,14 +146,9 @@ Changesets will always update the dependency if it would leave the old semver ra > [!WARNING] > This is only applied for packages which are already released in the current release. If A depends on B and we only release B then A won't be bumped. -## `changelog` - -> [!NOTE] Type: -> -> - `false` -> - `string` (path to a file) +## `changelog` (false or a path) -This option is for setting how the changelog for packages should be generated. If it is `false`, no changelogs will be generated. Setting it to a string specifies a path from where we will load the changelog generation functions. It expects to be a file that exports the following: +This option is for setting how the changelog for packages should be generated. If it is `false`, no changelogs will be generated. Setting it to a string specifies a path from where we will load the changelog generation functions. It expects a file that exports the following: ``` { @@ -198,29 +167,21 @@ You would specify our github changelog generator with: } ``` -For more details on these functions and information on how to write your own see [changelog-functions](/guide/advance/modifying-changelog-format) +If you want to disable thank you messages, add `"disableThanks": true` to the options. -## `bumpVersionsWithWorkspaceProtocolOnly` +For more details on these functions and information on how to write your own see [changelog-functions](../advance/modifying-changelog-format.md) -> [!NOTE] Type: -> -> - `boolean` +## `bumpVersionsWithWorkspaceProtocolOnly` (optional boolean) -Determines whether Changesets should only bump dependency ranges that use workspace protocol of packages that are part of the workspace. +Default value: `false` -## `snapshot` +Determines whether Changesets should only bump dependency ranges that use workspace protocol of packages that are part of the workspace. -> [!NOTE] Type -> -> - `object` (optional) +## `snapshot` (object or undefined) Default value: `undefined` -### `useCalculatedVersion` - -> [!NOTE] Type: -> -> - `boolean` (optional) +### `useCalculatedVersion` (optional boolean) Default value: `false` @@ -228,11 +189,7 @@ When `changesets version --snapshot` is used, the default behavior is to use `0. Setting `useCalculatedVersion: true` will change the default behavior and will use the calculated version, based on the changeset files. -### `prereleaseTemplate` - -> [!NOTE] Type: -> -> - `string` (optional) +### `prereleaseTemplate` (optional string) Default value: `undefined` (see note below) @@ -253,3 +210,62 @@ You can use the following placeholders for customizing the snapshot release vers **Default behavior** If you are not specifying `prereleaseTemplate`, the default behavior will fall back to using the following template: `{tag}-{datetime}`, and in cases where the tag is empty (`--snapshot` with no tag name), it will use `{datetime}` only. + +## `prettier` (optional boolean) + +This option configures whether Changesets will format its output using Prettier. When set to `false`, Changesets will skip formatting with Prettier. + +Default value: `true` + +```json +{ + "prettier": false +} +``` + +## `privatePackages` (object or false) + +This option is for setting how private packages should be handled. By default, Changesets will update the changelog for private packages and update their version, but will not create a tag. You can configure this option to change the default behavior. + +### `version` (optional boolean) + +Default value: `true` + +When `version` is set to `true`, Changesets will update the version for private packages. If set to `false`, Changesets will not update the version for private packages. + +### `tag` (optional boolean) + +Default value: `false` + +When `tag` is set to `true`, Changesets will create a tag for private packages. If set to `false`, Changesets will not create a tag for private packages. + +### Example + +```json +{ + "privatePackages": { + "version": true, + "tag": false + } +} +``` + +## `changedFilePatterns` (array of strings) + +Glob patterns for changed files that should mark a package as changed. Useful to fine-tune what counts as a change (e.g. only source files, ignoring test files, etc). + +Default value: + +```json +{ + "changedFilePatterns": ["**"] +} +``` + +Example: + +```json +{ + "changedFilePatterns": ["src/**", "lib/**"] +} +``` diff --git a/site/guide/intro/concepts.md b/site/guide/intro/concepts.md index f5cbfb8c5..de4ac8b5e 100644 --- a/site/guide/intro/concepts.md +++ b/site/guide/intro/concepts.md @@ -1,4 +1,4 @@ -# The core concepts of changesets +# A Detailed Explanation of Changesets Below, you will find a detailed explanation of what changesets are, and how they are being thought about. @@ -44,13 +44,13 @@ Change all the things This is useful because it breaks versioning into two steps: 1. Adding a changeset - can be done in a PR, by a contributor, while the change is fresh in their mind. -2. Versioning - combines all changesets, creates one version bump for each package based on the maximum version bump of each package, and updates dependencies where needed, write changelogs. Can then be reviewed as an aggregate. +2. Versioning - combines all changesets, creates one version bump for each package based on the maximum version bump of each package, updates dependencies where needed, and writes changelogs. Can then be reviewed as an aggregate. ## The tooling that makes this worthwhile -1. CLI generation of new changesets -2. Automated consumption of changesets to do versioning -3. Detection + surfacing of changesets in PRs +1. CLI generation of new changesets. +2. Automated consumption of changesets to do versioning. +3. Detection + surfacing of changesets in PRs. A tool to publish multiple packages from a mono-repo is also important, however does not need to be linked to this. diff --git a/site/guide/intro/dictionary.md b/site/guide/intro/dictionary.md index 5f3e7d60e..2e3dd67f9 100644 --- a/site/guide/intro/dictionary.md +++ b/site/guide/intro/dictionary.md @@ -2,7 +2,7 @@ This is a list of some words and phrases that are used in changesets which are helpful to know so that contributors to changesets have a shared understanding of various concepts in the project. -Several of these have associated type definitions, which you can find in [our types package](https://github.com/changesets/changesets/blob/main/packages/types/src/index.ts). +Several of these have associated type definitions, which you can find in [our types package](https://github.com/changesets/changesets/blob/main/packages/types). - **changeset** - an intent to release a set of packages at particular bump types with a summary of the changes made. Changesets are stackable, that is running `bump` will apply any number of changesets correctly. Changesets are used to generate further information, such as the `release information`, and the `release plan`. - **summary** - Information about the changes the changeset represents - this is written out to the `CHANGELOG.md` file of every package mentioned in the changeset. @@ -16,16 +16,16 @@ Several of these have associated type definitions, which you can find in [our ty - **single-package repo** - A repository which only contains a single package which is at the root of the repo - **multi-package repo/monorepo** - A repository which contains multiple packages, generally managed by [Bolt](https://github.com/boltpkg/bolt) or [Yarn Workspaces](https://yarnpkg.com/lang/en/docs/workspaces/). - **release line generators** - The `getReleaseLine` and `getDependencyReleaseLine` functions which are responsible for creating the lines inserted into changelog. A changelog entry for a particular release can be thought of as `releaseLineGenerators(changesets)` -- **fixed packages** - Fixed packages share a semver categorisation, such that all fixed packages have the same semver version and are always published together. The logistics of this are best left to our [fixed-packages](/guide/advance/fixed-packages) documentation. -- **linked packages** - Linked packages share a semver categorisation, such that all published linked packages have consistent new semver ranges. The logistics of this are best left to our [linked-packages](/guide/advance/linked-packages) documentation. +- **fixed packages** - Fixed packages share a semver categorisation, such that all fixed packages have the same semver version and are always published together. The logistics of this are best left to our [fixed-packages](../advance/fixed-packages.md) documentation. +- **linked packages** - Linked packages share a semver categorisation, such that all published linked packages have consistent new semver ranges. The logistics of this are best left to our [linked-packages](../advance/linked-packages.md) documentation. - **release instruction** An object containing an intent to release a single package, consisting of the package name and a bump type - **release plan** - A calculated object that shows everything a collection of changesets will release, and at what version, and how. This object includes a calculation of dependencies, and considerations for `linked` packages. - **absolutely correct semver** - making semver versioning decisions to ensure nothing less than major is capable of breaking a consumer's code. Because literally any change is technically capable of breaking a user's code, absolutely correct semver requires that all changes are major changes. - **pragmatically correct semver** - Making semver decisions that you believe to be correct, but may be in error. A pragmatic assessment is likely to change with the number of users of a project, and the API surface area of the project. Whenever we talk about 'correct semver', we are referring to 'pragmatically correct semver' - **dependency** - A package that is depended upon by another given package. -- **dependent** - A package which depends on another given package. This is frequently used in the context of the getting the dependents of a package so they can be released. +- **dependent** - A package which depends on another given package. This is frequently used in the context of getting the dependents of a package so they can be released. - **release** - The combination of versioning and publishing a package or packages which may include a build process before publishing -- **prereleases** - A pre-release is a release that uses a tag, and is not published as `latest` on npm. This is designed for when you want to share code, but are not yet ready for it to be the main package used by everyone. Pre-releases for packages are common, but pre-releases within a monorepo presents unique problems. You can see our exhaustive pre-release documentation [in our prereleases documentation](/guide/advance/pre-releases). In addition, there are two different approaches to pre-releases which are defined for use separately. +- **prereleases** - A pre-release is a release that uses a tag, and is not published as `latest` on npm. This is designed for when you want to share code, but are not yet ready for it to be the main package used by everyone. Pre-releases for packages are common, but pre-releases within a monorepo presents unique problems. You can see our exhaustive pre-release documentation [in our prereleases documentation](../advance/prereleases.md). In addition, there are two different approaches to pre-releases which are defined for use separately. - **Release Candidate (RC) prerelease** - An RC prerelease is done before an intended important release, likely a major release. It includes semver information about what the next intended release version is, a tag, and an iterated number for the prerelease. The output of this is intended to be committed, and then further work done on the branch. An example would be if I am on `1.0.0` of a package, and I want to do an RC for the next `major` version we would have: `package-one@2.0.0-my-tag.0`, and then the next publish is `package-one@2.0.0-my-tag.1`. - **snapshot prerelease** - A snapshot pre-release is intended to make it easy to test all changes at a particular git commit. It is published at `0.0.0` and uses the git hash as the tag. This should be used as a less formal method than a release candidate to make it easy to install and test changes. An example, if we have a package at `1.0.0`, and have a changeset for it to be `major` bumped, a snapshot release will be at `0.0.0-ABCDEFGH` (the last github hash). If we add more commits, the next snapshot would be `0.0.0-HIJKLMNOP`. diff --git a/site/guide/intro/getting-started.md b/site/guide/intro/getting-started.md index 0ff65346f..b02a8c4cb 100644 --- a/site/guide/intro/getting-started.md +++ b/site/guide/intro/getting-started.md @@ -1,45 +1,33 @@ -# Using changesets +# Using Changesets Changesets are designed to make your workflows easier, by allowing the person making contributions to make key decisions when they are making their contribution. Changesets hold two key bits of information: a version type (following [semver](https://semver.org/)), and change information to be added to a changelog. In addition, changesets were originally designed for implementation in [bolt monorepos](https://github.com/boltpkg/bolt). As such, in a monorepo context, changesets will handle bumping dependencies of changed packages, if that is required. -This guide is aimed at package maintainers adding changesets as a tool. For the information relevant to contributors, see [adding a changeset](/guide/basic/adding-a-changeset). +This guide is aimed at package maintainers adding changesets as a tool. For the information relevant to contributors, see [adding a changeset](../basic/adding-a-changeset.md). The overall tool after initialization should lead to a loop that looks like: 1. Changesets added along with each change 2. The version command is run when a release is ready, and the changes are verified -3. The publish command is run afterward. +3. The publish command is run afterwards. The second two steps can be made part of a CI process. ## Add the changeset tool ```shell -npm install @changesets/cli && npx changeset init +yarn add -D @changesets/cli && yarn changeset init ``` or ```shell -yarn add @changesets/cli && yarn changeset init -``` - -or - -```shell -pnpm i @changesets/cli && pnpm changeset init +npx @changesets/cli init ``` ## Adding changesets -```shell -npx changeset -``` - -or - ```shell yarn changeset ``` @@ -47,10 +35,9 @@ yarn changeset or ```shell -pnpm changeset +npx @changesets/cli ``` -> [!TIP] > Note: You can run `changeset add` to add a changeset if you want to, but running Changesets without any command works as well. ## Versioning and publishing @@ -58,13 +45,13 @@ pnpm changeset Once you decide you want to do a release, you can run ```shell -npx changeset version +yarn changeset version ``` or ```shell -yarn changeset version +npx @changesets/cli version ``` This consumes all changesets, and updates to the most appropriate semver version based on those changesets. It also writes changelog entries for each consumed changeset. @@ -72,13 +59,13 @@ This consumes all changesets, and updates to the most appropriate semver version We recommend at this step reviewing both the changelog entries and the version changes for packages. Once you are confident that these are correct, and have made any necessary tweaks to changelogs, you can publish your packages: ```shell -npx changeset publish +yarn changeset publish ``` or ```shell -yarn changeset publish +npx @changesets/cli publish ``` This will run npm publish in each package that is of a later version than the one currently listed on npm. diff --git a/site/guide/intro/what-are-changesets.md b/site/guide/intro/what-are-changesets.md index 3e1e71d08..cb82aefcc 100644 --- a/site/guide/intro/what-are-changesets.md +++ b/site/guide/intro/what-are-changesets.md @@ -1,5 +1,7 @@ # What are changesets? + + The changesets workflow is designed to help when people are making changes, all the way through to publishing. It lets contributors declare how their changes should be released, then we automate updating `package versions`, and `changelogs`, and `publishing new versions` of packages based on the provided information. Changesets has a focus on solving these problems for multi-package repositories, and keeps packages that rely on each other within the multi-package repository up-to-date, as well as making it easy to make changes to groups of packages. diff --git a/site/lib/apply-release-plan.md b/site/lib/apply-release-plan.md deleted file mode 100644 index 5ecec61f9..000000000 --- a/site/lib/apply-release-plan.md +++ /dev/null @@ -1,27 +0,0 @@ -# @changesets/apply-release-plan - -[![npm package](https://img.shields.io/npm/v/@changesets/apply-release-plan)](https://npmjs.com/package/@changesets/apply-release-plan) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -This takes a `releasePlan` object for changesets and applies the expected changes from that -release. This includes updating package versions, and updating changelogs. - -```ts -import applyReleasePlan from "@changesets/apply-release-plan"; -import { ReleasePlan, Config } from "@changesets/types"; -import { Packages } from '@manypkg/get-packages' - -await applyReleasePlan( - // The release plan to be applied - see @changesets/types for information about its shape - aReleasePlan: ReleasePlan, - // The packages that applyReleasePlan should be run for from @manypkg/get-packages - packages: Packages, - // A valid @changesets/config config - see @changesets/types for information about its shape - config: Config -); -``` - -Note that `apply-release-plan` does not validate the release plan's accuracy. - -To generate a release plan from written changesets use `@changesets/get-release-plan` diff --git a/site/lib/assemble-release-plan.md b/site/lib/assemble-release-plan.md deleted file mode 100644 index 9393cb8b2..000000000 --- a/site/lib/assemble-release-plan.md +++ /dev/null @@ -1,44 +0,0 @@ -# @changesets/assemble-release-plan - -[![npm package](https://img.shields.io/npm/v/@changesets/assemble-release-plan)](https://npmjs.com/package/@changesets/assemble-release-plan) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -Assemble a release plan for changesets from data about a repository. - -Usage - -```ts -import assembleReleasePlan from "@changesets/assemble-release-plan"; -import readChangesets from "@changesets/read"; -import { read } from "@changesets/config"; -import { getPackages } from "@manypkg/get-packages"; -import { readPreState } from "@changesets/pre"; - -const packages = await getPackages(cwd); -const preState = await readPreState(cwd); -const config = await read(cwd, packages); -const changesets = await readChangesets(cwd, sinceRef); - -const releasePlan = assembleReleasePlan(changesets, packages, config, preState); -``` - -Signature - -```ts -import { NewChangeset, Config, ReleasePlan } from "@changesets/types"; -import { Packages } from "@manypkg/get-packages"; - -assembleReleasePlan = ( - changesets: NewChangeset[], - packages: Packages, - config: Config, -) => ReleasePlan; -``` - -This package exists so assembling a release plan can be done without reading from disc. -This is useful primarily for testing within the changesets project, and when you cannot -run commands within the repository you want a release plan for (some CI cases). - -For most cases, you should use `@changesets/get-release-plan` which will read local changeset -files, config, and workspaces, to assemble the release plan from. diff --git a/site/lib/changelog-git.md b/site/lib/changelog-git.md deleted file mode 100644 index a29e75542..000000000 --- a/site/lib/changelog-git.md +++ /dev/null @@ -1 +0,0 @@ -# @changesets/git diff --git a/site/lib/changelog-github.md b/site/lib/changelog-github.md deleted file mode 100644 index 821f3caba..000000000 --- a/site/lib/changelog-github.md +++ /dev/null @@ -1 +0,0 @@ -# @changesets/github diff --git a/site/lib/cli.md b/site/lib/cli.md deleted file mode 100644 index e2bc93c3c..000000000 --- a/site/lib/cli.md +++ /dev/null @@ -1,198 +0,0 @@ -# @changesets/cli 🦋 - -[![npm package](https://img.shields.io/npm/v/@changesets/cli)](https://npmjs.com/package/@changesets/cli) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -The primary implementation of [changesets](https://github.com/Noviny/changesets). Helps you manage the versioning -and changelog entries for your packages, with a focus on versioning within a mono-repository (though we support -single-package repositories too). - -This package is intended as a successor to `@atlaskit/build-releases` with a more general focus. It works in -[bolt](https://www.npmjs.com/package/bolt) multi-package repositories, [yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/) multi-package repositories, and -in single-package repositories. - -## Getting Started - -If you are installing this in a monorepo run - -``` -yarn add @changesets/cli -yarn changeset init -``` - -otherwise run - -``` -yarn add --dev @changesets/cli -yarn changeset init -``` - -From here you are set up to use changesets. Add your first changeset by running - -``` -yarn changeset -``` - -and following the prompts that you are presented with. - -Below you can find a basic workflow for maintainers to help them use changesets, which you can vary to meet your own needs. - -## Core Concepts - -The core concept that `changesets` follows is that contributors to a repository should be able to declare an intent to release, and that multiple intents should be able to be combined sensibly. Sensibly here refers to if there is one intent to release button as a 'minor' and another to release button as a 'patch', only one release will be made, at the higher of the two versions. - -A single `changeset` is an intent to release stored as data, with the information we need to combine multiple changesets and coordinate releases. It will also update internal dependencies within a multi-package repository. - -## Base workflow - -Contributor runs: - -``` -yarn changeset -``` - -or - -``` -npx changeset -``` - -and answers the provided questions. - -When the maintainer wants to release packages, they should run - -``` -yarn changeset version -``` - -or - -``` -npx changeset version -``` - -and then - -``` -yarn changeset publish -``` - -or - -``` -npx changeset publish -``` - -The commands are explained further below. - -## Commands - -### init - -``` -changeset init -``` - -This command sets up the `.changeset` folder. It generates a readme and a config file. The config file includes the default options, as well as comments on what these options represent. You should run this command once, when you are setting up `changesets`. - -To publish public packages to NPM, you'll need to edit `.changeset/config.json` and change `"access": "restricted",` to `"access": "public",`. Read more about [access in config file options](https://github.com/changesets/changesets/blob/main/docs/config-file-options.md#access-restricted--public). The `publishConfig` of each `package.json` is also respected and takes a priority over monorepo-wide setting in `.changeset/config.json`. - -### add - -``` -changeset [--empty] [--open] -``` - -or - -``` -changeset add [--empty] [--open] -``` - -This command will ask you a series of questions, first about what packages you want to release, then what semver bump type for each package, then it will ask for a summary of the entire changeset. At the final step it will show the changeset it will generate, and confirm that you want to add it. - -Once confirmed, the changeset will write a Markdown file that contains the summary and YAML front matter which stores the packages that will be released and the semver bump types for them. - -A changeset that major bumps `@changesets/cli` would look like this: - -```md ---- -"@changesets/cli": major ---- - -A description of the major changes. -``` - -If you want to modify this file after it's generated, that's completely fine or if you want to write changeset files yourself, that's also fine. - -- `--empty` - allows you to create an empty changeset if no packages are being bumped, usually only required if you have CI that blocks merges without a changeset. - -A changeset created with the `empty` flag would look like this: - -```md ---- ---- -``` - -If you set the `commit` option in the config, the command will add the updated changeset files and then commit them. - -- `--open` - opens the created changeset in an external editor - -### version - -``` -changeset version -``` - -Updates the versions for all packages described in changesets since last release along with any dependents inside the repo that are out of range. - -Will also create/append to a CHANGELOG file for each package using the summaries from the changesets. - -We recommend making sure changes made from this command are merged back into the base branch before you run `publish`. - -This command will read then delete changesets on disk, ensuring that they are only used once. - -### publish - -``` -changeset publish [--otp={token}] -``` - -Publishes to NPM repo, and creates git tags. Because this command assumes that last commit is the release commit you should not commit any changes between calling `version` and `publish`. These commands are separate to enable you to check if release commit is accurate. - -- `--otp={token}` - allows you to provide an npm one-time password if you have auth and writes enabled on npm. The CLI also prompts for the OTP if it's not provided with the `--otp` option. - -**NOTE:** You will still need to push your changes back to the base branch after this - -``` -git push --follow-tags -``` - -### status - -``` -status [--verbose] [--output={filePath}] [--since={gitTag}] -``` - -The status command provides information about the changesets that currently exist. If there are changes to packages but no changesets are present, it exits with error status code `1`. - -- `--verbose` - use if you want to know the new versions, and get a link to the relevant changeset summary. - -- `--output` - allows you to write the json object of the status out, for consumption by other tools, such as CI. - -- `--since` - to only display information about changesets since a specific branch or git tag. While this can be - used to add a CI check for changesets, we recommend not doing this. We instead recommend using the [changeset bot](https://github.com/apps/changeset-bot) - to detect pull requests missing changesets, as not all pull requests need one. - -### pre - -``` -pre [exit|enter {tag}] -``` - -The pre command enters and exits pre mode. The command does not do any actual versioning, when doing a prerelease, you should run `changeset pre enter next`(or a different tag, the tag is what is in versions and is the npm dist tag) and then do the normal release process with `changeset version` and `changeset publish`. For more information about the pre command, see [the prereleases documentation](/guide/advance/pre-releases). - -### Bumping peerDependencies - -In almost all circumstances, internal packages will be bumped as a patch. The one exception is when the dependency is a `peerDependency`, in which case the change will become a major. diff --git a/site/lib/config.md b/site/lib/config.md deleted file mode 100644 index 146179f06..000000000 --- a/site/lib/config.md +++ /dev/null @@ -1,25 +0,0 @@ -# @changesets/config - -> Utilities for reading and parsing Changeset's config - -[![npm package](https://img.shields.io/npm/v/@changesets/config)](https://npmjs.com/package/@changesets/config) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -```tsx -import { parse, read, ValidationError } from "@changesets/config"; - -let config = await read(process.cwd(), workspaces); - -let config = parse({ commit: true }, workspaces); - -try { - return parse({ commit: true }, workspaces); -} catch (err) { - if (err instanceof ValidationError) { - let message = err.message; - } else { - throw err; - } -} -``` diff --git a/site/lib/errors.md b/site/lib/errors.md deleted file mode 100644 index 119cd6239..000000000 --- a/site/lib/errors.md +++ /dev/null @@ -1,7 +0,0 @@ -# @changesets/errors - -[![npm package](https://img.shields.io/npm/v/@changesets/errors)](https://npmjs.com/package/@changesets/errors) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -Error classes for Changesets. diff --git a/site/lib/get-dependents-graph.md b/site/lib/get-dependents-graph.md deleted file mode 100644 index c439033d5..000000000 --- a/site/lib/get-dependents-graph.md +++ /dev/null @@ -1,16 +0,0 @@ -# @changesets/get-dependents-graph - -[![npm package](https://img.shields.io/npm/v/@changesets/get-dependents-graph)](https://npmjs.com/package/@changesets/get-dependents-graph) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -Small helper utility extracted from bolt to get a graph of relationships between packages. - -```ts -import { getDependentsGraph } from "@changesets/get-dependents-graph"; -import { getPackages } from "@manypkg/get-packages"; - -let { graph, valid } = getDependentsGraph(await getPackages(cwd)); -``` - -Mostly published for use in [changesets](https://www.npmjs.com/package/@changesets/cli) diff --git a/site/lib/get-github-info.md b/site/lib/get-github-info.md deleted file mode 100644 index 868a36feb..000000000 --- a/site/lib/get-github-info.md +++ /dev/null @@ -1,85 +0,0 @@ -# @changesets/get-github-info - -[![npm package](https://img.shields.io/npm/v/@changesets/get-github-info)](https://npmjs.com/package/@changesets/get-github-info) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -> Get the GitHub username and PR number from a commit. Intended for use with changesets. - -## Getting Started - -> Note: This assumes you already have changesets setup. - -To use `@changesets/get-github-info`, you'll need to install it and you'll probably also want `dotenv` to provide a GitHub personal access token via a `.env` file. - -```bash -yarn add --dev @changesets/get-github-info dotenv -``` - -or - -```bash -npm install --save-dev @changesets/get-github-info dotenv -``` - -Then you can use it in your `.changeset/config.js` like this. - -```jsx -require("dotenv").config(); -const { getInfo } = require("@changesets/get-github-info"); - -// ... - -const getReleaseLine = async (changeset, type) => { - const [firstLine, ...futureLines] = changeset.summary - .split("\n") - .map((l) => l.trimRight()); - // getInfo exposes the GH username and PR number if you want them directly - // but it also exposes a set of links for the commit, PR and GH username - let { user, pull, links } = await getInfo({ - // replace this with your own repo - repo: "Noviny/changesets", - commit: changeset.commit, - }); - let returnVal = `- ${links.commit}${ - links.pull === null ? "" : ` ${links.pull}` - }${links.user === null ? "" : ` Thanks ${links.user}!`}: ${firstLine}`; - if (futureLines.length > 0) { - returnVal += `\n${futureLines.map((l) => ` ${l}`).join("\n")}`; - } - return returnVal; -}; - -// ... -``` - -You'll need to [get a GitHub personal access token](https://github.com/settings/tokens/new) with `read:user` and `repo:status` permissions, and add it to a `.env` file. - -```bash -GITHUB_TOKEN=token_here -``` - -You can now bump your packages and changelogs with `changeset version` and it'll have the GitHub info. 🎉 - -## API - -```ts -type Info = { - user: string | null; - pull: number | null; - links: { - commit: string; - pull: string | null; - user: string | null; - }; -}; - -type Options = { - commit: string; - repo: string; -}; - -export function getInfo(options: Options): Info { - // magic... -} -``` diff --git a/site/lib/get-release-plan.md b/site/lib/get-release-plan.md deleted file mode 100644 index 19a06ae76..000000000 --- a/site/lib/get-release-plan.md +++ /dev/null @@ -1,26 +0,0 @@ -# @changesets/get-release-plan - -[![npm package](https://img.shields.io/npm/v/@changesets/get-release-plan)](https://npmjs.com/package/@changesets/get-release-plan) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -A function that reads information about the current repository - -```js -import getReleasePlan from "@changesets/get-release-plan"; - -const releasePlan = await getReleasePlan(cwd, since, passedConfig); -``` - -## cwd: string - -The directory to run `getReleasePlan` in - most often `process.cwd()` - -## since: string - -Sets whether to use all changesets present, or only those changesets that are new since the branch -diverged from another one. - -## passedConfig?: Config - -The changeset config options as defined in `@changesets/types`. This is optional, and can be used to overwrite any written config options. diff --git a/site/lib/get-version-range-type.md b/site/lib/get-version-range-type.md deleted file mode 100644 index ac56e6b5e..000000000 --- a/site/lib/get-version-range-type.md +++ /dev/null @@ -1,10 +0,0 @@ -# @changesets/get-version-range-type - -[![npm package](https://img.shields.io/npm/v/@changesets/get-version-range-type)](https://npmjs.com/package/@changesets/get-version-range-type) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -Simple function that takes in a string which is a version range (ie `^1.0.0`, `~3.5.1`, `2.0.0`) -and returns the range definition. - -A helper published mostly to ensure consistency across several changeset packages. diff --git a/site/lib/git.md b/site/lib/git.md deleted file mode 100644 index 1b219d8d9..000000000 --- a/site/lib/git.md +++ /dev/null @@ -1,9 +0,0 @@ -# @changesets/git - -[![npm package](https://img.shields.io/npm/v/@changesets/git)](https://npmjs.com/package/@changesets/git) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -A collection of helper functions used internally in changesets to make git operations easier. - -Published documentation is likely to remain sparse. diff --git a/site/lib/logger.md b/site/lib/logger.md deleted file mode 100644 index c7a83ca1d..000000000 --- a/site/lib/logger.md +++ /dev/null @@ -1,44 +0,0 @@ -# @changesets/logger - -[![npm package](https://img.shields.io/npm/v/@changesets/logger)](https://npmjs.com/package/@changesets/logger) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -### Usage - -```js -import { error } from '@changesets/logger"; - -error('message part 1', 'message part 2'); -``` - -### Package Exports - -**error**: Use `error` to print error messages upon which users which immediately action to complete the task. - -**info**: Use `info` to print informational messages to user. - -**log**: Use `log` to print messages don't fall in any other specific category. For example, message to show title of the step being performed by the changesets tool. - -**success**: Use `success` to assert to users that their instructions have completed successfully. - -**warn**: Use `warn` to print warning messages, something that user could action on now or later without much impact of their work. - -### Silencing Messages In Tests - -Use the `@changesets/test-utils` package to silence the logs in test cases. - -For example: - -```js -import { temporarilySilenceLogs } from "@changesets/test-utils"; -import { log } from "@changesets/logger"; - -temporarilySilenceLogs(); - -// Now the logs in this test file are not actually logged to std out -log("I am not logged"); - -// Use console.log to log messages in tests if required -console.log("Yay, I am logged"); -``` diff --git a/site/lib/parse.md b/site/lib/parse.md deleted file mode 100644 index f26915b17..000000000 --- a/site/lib/parse.md +++ /dev/null @@ -1,47 +0,0 @@ -# @changesets/parse - -[![npm package](https://img.shields.io/npm/v/@changesets/parse)](https://npmjs.com/package/@changesets/parse) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -Parses a changeset from its written format to a data object. - -```js -import parse from "@changesets/parse"; - -const changeset = `--- -"@changesets/something": minor -"@changesets/something-else": patch ---- - -A description of a minor change`; - -const parsedChangeset = parse(changeset); -``` - -For example, it can convert: - -```md ---- -"@changesets/something": minor -"@changesets/something-else": patch ---- - -A description of a minor change -``` - -to - -```json -{ - "summary": "A description of a minor change", - "releases": [ - { "name": "@changesets/something", "type": "minor" }, - { "name": "@changesets/something-else", "type": "patch" } - ] -} -``` - -Note that this is not quite a complete Changeset for most tools as it lacks an `id`. - -For written changesets, the id is normally given as the file name, which parse is not aware of. diff --git a/site/lib/pre.md b/site/lib/pre.md deleted file mode 100644 index 7c8d98541..000000000 --- a/site/lib/pre.md +++ /dev/null @@ -1,32 +0,0 @@ -# @changesets/pre - -[![npm package](https://img.shields.io/npm/v/@changesets/pre)](https://npmjs.com/package/@changesets/pre) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -Enter and exit pre mode in a Changesets repo. - -## Usage - -```ts -import { enterPre, exitPre } from "@changesets/pre"; - -await enterPre(cwd, tag); - -let preState = await readPreState(cwd); - -// version packages with @changesets/cli or get a release plan and apply it -await exitPre(cwd); -``` - -This package is used by internally by Changesets to enter and exit pre mode along with reading the pre state for the `publish` and `version` commands, you should only need it if you're using `@changesets/assemble-release-plan`, implementing Changesets or want to enter or exit pre mode programmatically. - -## Types - -```ts -import { PreState } from "@changesets/types"; - -export function enterPre(cwd: string, tag: string): Promise; -export function exitPre(cwd: string): Promise; -export function readPreState(cwd: string): Promise; -``` diff --git a/site/lib/read.md b/site/lib/read.md deleted file mode 100644 index 5855a9320..000000000 --- a/site/lib/read.md +++ /dev/null @@ -1,15 +0,0 @@ -# @changesets/read - -[![npm package](https://img.shields.io/npm/v/@changesets/read)](https://npmjs.com/package/@changesets/read) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -Read in all changesets from a repository. - -```js -import read from "@changesets/read"; - -let changesets = await getChangesets(cwd); -``` - -This returns an array of formatted changesets. diff --git a/site/lib/release-utils.md b/site/lib/release-utils.md deleted file mode 100644 index 231272320..000000000 --- a/site/lib/release-utils.md +++ /dev/null @@ -1 +0,0 @@ -# @changesets/release-utils diff --git a/site/lib/should-skip-package.md b/site/lib/should-skip-package.md deleted file mode 100644 index c7446a24d..000000000 --- a/site/lib/should-skip-package.md +++ /dev/null @@ -1 +0,0 @@ -# @changesets/should-skip-package diff --git a/site/lib/types.md b/site/lib/types.md deleted file mode 100644 index 3df476cac..000000000 --- a/site/lib/types.md +++ /dev/null @@ -1,21 +0,0 @@ -# @changesets/types - -[![npm package](https://img.shields.io/npm/v/@changesets/types)](https://npmjs.com/package/@changesets/types) - -[//]: # "[![View changelog](https://img.shields.io/badge/Explore%20Changelog-brightgreen)](./CHANGELOG.md)" - -A package of types for use in changesets, or projects wishing to extend them. - -Of these, the most useful types are: - -## NewChangeset - -The format for a changeset as of changesets version 2. - -## ChangelogFunctions - -The shape of the object used for generating changelog entries. - -## ReleasePlan - -The combined object used to version packages and update changelogs. diff --git a/site/lib/write.md b/site/lib/write.md deleted file mode 100644 index 850357cc7..000000000 --- a/site/lib/write.md +++ /dev/null @@ -1,43 +0,0 @@ -# @changesets/write - -Writes a changeset to a file. - -```js -import write from "@changesets/write"; - -const changeset = { - summary: "A description of a minor change", - releases: [ - { name: "@changesets/something", type: "minor" }, - { name: "@changesets/something-else", type: "patch" }, - ], -}; - -const uniqueId = await write(changeset, cwd); -console.log(uniqueId); // orange-foxes-waggle -``` - -For example, it can convert: - -```json -{ - "summary": "A description of a minor change", - "releases": [ - { "name": "@changesets/something", "type": "minor" }, - { "name": "@changesets/something-else", "type": "patch" } - ] -} -``` - -to - -```markdown ---- -"@changesets/something": minor -"@changesets/something-else": patch ---- - -A description of a minor change -``` - -This package will take care of generating a unique id for the changeset. diff --git a/site/package.json b/site/package.json index d3fce80a6..dc47944ea 100644 --- a/site/package.json +++ b/site/package.json @@ -10,6 +10,7 @@ "preview": "vitepress preview" }, "devDependencies": { + "oxc-minify": "^0.128.0", "vitepress": "^2.0.0-alpha.17" } } From 5bab57183ceee152f77d29c6b5a93f3c6a844fd5 Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 6 May 2026 01:09:59 +0800 Subject: [PATCH 03/80] Remove docsearch dependencies --- pnpm-lock.yaml | 29 +++++------------------------ pnpm-workspace.yaml | 2 ++ 2 files changed, 7 insertions(+), 24 deletions(-) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index aa94292e4..982de3de6 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -6,6 +6,8 @@ settings: excludeLinksFromLockfile: false overrides: + vitepress>@docsearch/js: '-' + vitepress>@docsearch/sidepanel-js: '-' vitepress>vite: ^8.0.0 importers: @@ -1069,12 +1071,6 @@ packages: '@docsearch/css@4.6.3': resolution: {integrity: sha512-nlOwcXcsNAptQl4vlL4MA78qNJKO0Qlds5GuBjCoePgkebTXLSf8Qt1oyZ3YBshYupKXG9VRGEsk1zr23d+bzQ==} - '@docsearch/js@4.6.3': - resolution: {integrity: sha512-qUIX2b4Apew3tv4F0qhmgShsl/Lfw4m6mqv/5/5dWNxwTcDdLMp2s3YwZ+NMGh3IKCg0pBaXm7Q5VdyU5Rj+cQ==} - - '@docsearch/sidepanel-js@4.6.3': - resolution: {integrity: sha512-grGSmvXzG0if+mrzdIKykvpIAuEQ9u0sEJ2eLRRCaQfJvsWqh2C2/aY04bIzWvDh7myi5rvl8D+tUNsVrjYQ3A==} - '@emnapi/core@1.10.0': resolution: {integrity: sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw==} @@ -2954,10 +2950,6 @@ packages: resolution: {integrity: sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==} engines: {node: '>=18'} - tinyglobby@0.2.15: - resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==} - engines: {node: '>=12.0.0'} - tinyglobby@0.2.16: resolution: {integrity: sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==} engines: {node: '>=12.0.0'} @@ -3896,10 +3888,6 @@ snapshots: '@docsearch/css@4.6.3': {} - '@docsearch/js@4.6.3': {} - - '@docsearch/sidepanel-js@4.6.3': {} - '@emnapi/core@1.10.0': dependencies: '@emnapi/wasi-threads': 1.2.1 @@ -4030,7 +4018,7 @@ snapshots: dependencies: jju: 1.4.0 js-yaml: 4.1.1 - tinyglobby: 0.2.15 + tinyglobby: 0.2.16 '@mswjs/interceptors@0.39.8': dependencies: @@ -4464,7 +4452,7 @@ snapshots: debug: 4.4.3 minimatch: 10.2.5 semver: 7.7.3 - tinyglobby: 0.2.15 + tinyglobby: 0.2.16 ts-api-utils: 2.5.0(typescript@6.0.3) typescript: 6.0.3 transitivePeerDependencies: @@ -5827,11 +5815,6 @@ snapshots: tinyexec@1.0.2: {} - tinyglobby@0.2.15: - dependencies: - fdir: 6.5.0(picomatch@4.0.4) - picomatch: 4.0.4 - tinyglobby@0.2.16: dependencies: fdir: 6.5.0(picomatch@4.0.4) @@ -5951,8 +5934,6 @@ snapshots: vitepress@2.0.0-alpha.17(@types/node@24.12.2)(oxc-minify@0.128.0)(postcss@8.5.13)(terser@5.44.1)(typescript@6.0.3): dependencies: '@docsearch/css': 4.6.3 - '@docsearch/js': 4.6.3 - '@docsearch/sidepanel-js': 4.6.3 '@iconify-json/simple-icons': 1.2.80 '@shikijs/core': 3.23.0 '@shikijs/transformers': 3.23.0 @@ -6016,7 +5997,7 @@ snapshots: std-env: 4.1.0 tinybench: 2.9.0 tinyexec: 1.0.2 - tinyglobby: 0.2.15 + tinyglobby: 0.2.16 tinyrainbow: 3.1.0 vite: 8.0.10(@types/node@24.12.2)(terser@5.44.1) why-is-node-running: 2.3.0 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 824d9063f..dd535acac 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -12,4 +12,6 @@ dedupePeerDependents: true shellEmulator: true overrides: + 'vitepress>@docsearch/js': '-' + 'vitepress>@docsearch/sidepanel-js': '-' 'vitepress>vite': ^8.0.0 From b6644e01020ff8be95b61b402244951eecbd0ad6 Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 6 May 2026 10:26:48 +0800 Subject: [PATCH 04/80] Adjust colors --- package.json | 6 +-- site/.vitepress/config.ts | 24 ++++++++- site/.vitepress/theme/custom.css | 64 +++++++++++++++--------- site/.vitepress/theme/index.ts | 2 +- site/index.md | 34 ++++++++----- site/public/logo-dark.svg | 25 +++++++++ site/public/{logo.svg => logo-light.svg} | 0 7 files changed, 113 insertions(+), 42 deletions(-) create mode 100644 site/public/logo-dark.svg rename site/public/{logo.svg => logo-light.svg} (100%) diff --git a/package.json b/package.json index fb249afee..733f0b6aa 100644 --- a/package.json +++ b/package.json @@ -13,9 +13,9 @@ "test": "vitest", "types:check": "tsc", "check-all": "node --run build && node --run test -- run && node --run types:check && node --run lint && node --run format", - "docs:dev": "pnpm --filter=./site dev", - "docs:build": "pnpm --filter=./site build", - "docs:preview": "pnpm --filter=./site preview", + "site:dev": "pnpm --filter=./site dev", + "site:build": "pnpm --filter=./site build", + "site:preview": "pnpm --filter=./site preview", "version-packages": "node --run changeset version && node --run format:fix", "release": "node --run build && node --run changeset publish", "changeset": "NODE_OPTIONS=--experimental-strip-types packages/cli/bin.js" diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts index 02c2e1e65..137cb04c4 100644 --- a/site/.vitepress/config.ts +++ b/site/.vitepress/config.ts @@ -1,4 +1,7 @@ import { defineConfig } from "vitepress"; +import packageJson from "../../packages/cli/package.json" with { type: "json" }; + +const changesetsVersion = packageJson.version; export default defineConfig({ title: "Changesets", @@ -8,13 +11,19 @@ export default defineConfig({ cleanUrls: true, themeConfig: { - logo: "/logo.svg", + logo: { + light: "/logo-light.svg", + dark: "/logo-dark.svg", + alt: "Changesets logo", + }, editLink: { pattern: "https://github.com/changesets/changesets/edit/main/site/:path", }, socialLinks: [ + { icon: "discord", link: "https://chat.changesets.dev" }, { icon: "github", link: "https://github.com/changesets/changesets" }, + { icon: "npm", link: "https://npmx.dev/package/@changesets/cli" }, ], search: { @@ -34,6 +43,19 @@ export default defineConfig({ text: "FAQ", link: "/faq/publishing-in-monorepos", }, + { + text: `v${changesetsVersion}`, + items: [ + { + text: `v${changesetsVersion}`, + link: `https://github.com/changesets/changesets/releases/tag/%40changesets%2Fcli%40${changesetsVersion}`, + }, + { + text: "Changelog", + link: "https://github.com/changesets/changesets/blob/main/packages/cli/CHANGELOG.md", + }, + ], + }, ], sidebar: { diff --git a/site/.vitepress/theme/custom.css b/site/.vitepress/theme/custom.css index ccb83fb02..7a7bf537a 100644 --- a/site/.vitepress/theme/custom.css +++ b/site/.vitepress/theme/custom.css @@ -1,32 +1,48 @@ -@media (min-width: 640px) { - .VPHero .container .main .text { - font-size: 48px !important; - } -} +/** + * Customize default theme styling by overriding CSS variables: + * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css + */ :root { - --vp-c-brand-1: #124787; - --vp-c-brand-2: #165db3; - --vp-c-brand-3: #5bb7f3; + --vp-c-brand-1: #006dcc; + --vp-c-brand-2: #006cc8; + --vp-c-brand-3: #1f9ce2; + --vp-c-brand-soft: rgba(102, 204, 255, 0.14); - --vp-home-hero-name-background: linear-gradient( - 135deg, - #124787 10%, - #5bb7f3 100% + --vp-home-hero-name-color: transparent; + --vp-home-hero-name-background: linear-gradient( + 135deg, + var(--vp-c-brand-1) 10%, + var(--vp-c-brand-3) 90% ); - --vp-home-hero-image-background-image: linear-gradient( - -60deg, - #a5ccf9 50%, - #65baf6 50% + 135deg, + var(--vp-c-brand-1) 50%, + var(--vp-c-brand-3) 50% ); - --vp-home-hero-image-filter: blur(50px); + --vp-home-hero-image-filter: blur(80px) opacity(0.7); + + /* Add transparency for navigation bars */ + --vp-nav-bg-color: color-mix(in srgb, var(--vp-c-bg) 70%, transparent); + --vp-local-nav-bg-color: color-mix(in srgb, var(--vp-c-bg) 70%, transparent); +} + +.dark { + --vp-c-brand-1: #9ccfff; + --vp-c-brand-2: #4d9ee4; + --vp-c-brand-3: #2a7fc4; + --vp-c-brand-soft: rgba(77, 158, 228, 0.16); - --vp-button-brand-border: #124787; - --vp-button-brand-text: #f4f8fd; - --vp-button-brand-bg: #124787; + --vp-home-hero-image-filter: blur(80px) opacity(0.5); +} + +/* Ensure tagline stays single line */ +.VPHero .container .main > .heading > .text { + font-size: 48px; +} - --vp-button-brand-hover-border: #165db3; - --vp-button-brand-hover-text: #fff; - --vp-button-brand-hover-bg: #165db3; -} \ No newline at end of file +/* Blur effect for navigation bars */ +.VPNavBar, +.VPLocalNav { + backdrop-filter: saturate(180%) blur(20px); +} diff --git a/site/.vitepress/theme/index.ts b/site/.vitepress/theme/index.ts index a9e217fd2..91ff50b15 100644 --- a/site/.vitepress/theme/index.ts +++ b/site/.vitepress/theme/index.ts @@ -1,5 +1,5 @@ import DefaultTheme from "vitepress/theme"; -import "./style.css"; +// import "./style.css"; import "./custom.css"; export default DefaultTheme; diff --git a/site/index.md b/site/index.md index a36b338aa..2fda4396d 100644 --- a/site/index.md +++ b/site/index.md @@ -1,13 +1,13 @@ --- -# https://vitepress.dev/reference/default-theme-home-page layout: home hero: - name: "Changesets" - text: "Version and Changelogs" + name: Changesets + text: Version and Changelogs tagline: A tool to manage versioning and changelogs image: - src: /logo.svg + light: /logo-light.svg + dark: /logo-dark.svg alt: Changesets logo actions: - theme: brand @@ -18,18 +18,26 @@ hero: link: https://github.com/changesets/changesets features: - - icon: ⚡ + - icon: ⚡️ title: Automated Versioning - details: Automatically updates versions based on change types, ensuring consistent dependencies. + details: Automatically updates versions based on change types. - icon: 📦 - title: Support for Multi-package Repositories + title: Monorepo Support details: Simplifies managing multiple packages within one repository. - icon: 📖 - title: Change Log Generation - details: Automatically creates change logs for easy tracking of updates and new features. - - icon: 🚀 - title: CI/CD Workflow Integration - details: Streamlines version control and releases through automatic pull requests and release triggers. + title: Changelog Generation + details: Automatically creates package changelogs. + - icon: 🔄 + title: CI/CD Integration + details: Release through automated pull requests and release triggers. --- - + + + diff --git a/site/public/logo-dark.svg b/site/public/logo-dark.svg new file mode 100644 index 000000000..d1cfee859 --- /dev/null +++ b/site/public/logo-dark.svg @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/site/public/logo.svg b/site/public/logo-light.svg similarity index 100% rename from site/public/logo.svg rename to site/public/logo-light.svg From 608502a85fb84f0d274c10df90387fd40d813990 Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 6 May 2026 11:11:27 +0800 Subject: [PATCH 05/80] Move pages --- site/.vitepress/config.ts | 100 ++++-------------- site/guide/{advance => advanced}/decisions.md | 0 .../experimental-options.md | 0 .../{advance => advanced}/fixed-packages.md | 0 .../{advance => advanced}/linked-packages.md | 0 .../modifying-changelog-format.md | 0 .../{advance => advanced}/prereleases.md | 0 .../advanced}/publishing-in-monorepos.md | 0 .../snapshot-releases.md | 2 +- .../{advance => advanced}/versioning-apps.md | 0 site/guide/basic/adding-a-changeset.md | 2 +- site/guide/{api => basic}/cli.md | 10 +- site/guide/basic/configuration.md | 8 +- .../introduction}/common-questions.md | 0 .../guide/{intro => introduction}/concepts.md | 0 .../{intro => introduction}/dictionary.md | 6 +- .../getting-started.md | 0 .../what-are-changesets.md | 2 +- site/index.md | 2 +- 19 files changed, 35 insertions(+), 97 deletions(-) rename site/guide/{advance => advanced}/decisions.md (100%) rename site/guide/{advance => advanced}/experimental-options.md (100%) rename site/guide/{advance => advanced}/fixed-packages.md (100%) rename site/guide/{advance => advanced}/linked-packages.md (100%) rename site/guide/{advance => advanced}/modifying-changelog-format.md (100%) rename site/guide/{advance => advanced}/prereleases.md (100%) rename site/{faq => guide/advanced}/publishing-in-monorepos.md (100%) rename site/guide/{advance => advanced}/snapshot-releases.md (95%) rename site/guide/{advance => advanced}/versioning-apps.md (100%) rename site/guide/{api => basic}/cli.md (95%) rename site/{faq => guide/introduction}/common-questions.md (100%) rename site/guide/{intro => introduction}/concepts.md (100%) rename site/guide/{intro => introduction}/dictionary.md (95%) rename site/guide/{intro => introduction}/getting-started.md (100%) rename site/guide/{intro => introduction}/what-are-changesets.md (92%) diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts index 137cb04c4..2955ce163 100644 --- a/site/.vitepress/config.ts +++ b/site/.vitepress/config.ts @@ -33,15 +33,7 @@ export default defineConfig({ nav: [ { text: "Guide", - link: "/guide/intro/what-are-changesets", - }, - { - text: "Lib", - link: "/lib/apply-release-plan", - }, - { - text: "FAQ", - link: "/faq/publishing-in-monorepos", + link: "/introduction/getting-started", }, { text: `v${changesetsVersion}`, @@ -59,17 +51,17 @@ export default defineConfig({ ], sidebar: { - "/guide": { - base: "guide", + "/guide/": { items: [ { - text: "Intro", - base: "/guide/intro/", + text: "Introduction", + base: "/guide/introduction/", items: [ - { text: "What are Changesets", link: "what-are-changesets" }, + { text: "What are Changesets?", link: "what-are-changesets" }, + { text: "Getting Started", link: "getting-started" }, + { text: "Common Questions", link: "common-questions" }, { text: "Concepts", link: "concepts" }, { text: "Dictionary", link: "dictionary" }, - { text: "Getting Stared", link: "getting-started" }, ], }, { @@ -77,88 +69,34 @@ export default defineConfig({ base: "/guide/basic/", items: [ { text: "Adding a Changeset", link: "adding-a-changeset" }, - { - text: "Automating Changesets", - link: "automating-changesets", - }, { text: "Checking for Changesets", link: "checking-for-changesets", }, + { text: "Automating Changesets", link: "automating-changesets" }, { text: "Configuration", link: "configuration" }, + { text: "CLI Reference", link: "cli" }, ], }, { - text: "Advance", - base: "/guide/advance/", + text: "Advanced", + base: "/guide/advanced/", items: [ + { text: "Decisions", link: "decisions" }, + { text: "Experimental Options", link: "experimental-options" }, { text: "Fixed Packages", link: "fixed-packages" }, { text: "Linked Packages", link: "linked-packages" }, { - text: "Modifying Changelog Format", - link: "modifying-changelog-format", + text: "Modifying Changelog Formats", + link: "modifying-changelog-formats", }, - { text: "Pre Releases", link: "pre-releases" }, - { text: "Snapshot Releases", link: "snapshot-releases" }, - { text: "Versioning Apps", link: "versioning-apps" }, - ], - }, - { - text: "Api Reference", - base: "/guide/api/", - items: [{ text: "CLI", link: "cli" }], - }, - ], - }, - "/faq": { - base: "faq", - items: [ - { - base: "/faq/", - items: [ + { text: "Prereleases", link: "prereleases" }, { - text: "Pushing in Monorepos?", + text: "Publishing in Monorepos", link: "publishing-in-monorepos", }, - ], - }, - ], - }, - "/lib": { - base: "lib", - items: [ - { - base: "/lib/", - items: [ - { text: "apply-release-plan", link: "apply-release-plan" }, - { - text: "assemble-release-plan", - link: "assemble-release-plan", - }, - { text: "changelog-git", link: "changelog-git" }, - { text: "changelog-github", link: "changelog-github" }, - { text: "cli", link: "cli" }, - { text: "git", link: "git" }, - { text: "pre", link: "pre" }, - { text: "release-utils", link: "release-utils" }, - { text: "get-release-plan", link: "get-release-plan" }, - { text: "get-github-info", link: "get-github-info" }, - { - text: "get-version-range-type", - link: "get-version-range-type", - }, - { - text: "get-dependents-graph", - link: "get-dependents-graph", - }, - { text: "logger", link: "logger" }, - { text: "parse", link: "parse" }, - { text: "should-skip-package", link: "should-skip-package" }, - { text: "types", link: "types" }, - { text: "config", link: "config" }, - { text: "errors", link: "errors" }, - { text: "read", link: "read" }, - { text: "write", link: "write" }, + { text: "Snapshot Releases", link: "snapshot-releases" }, + { text: "Versioning apps", link: "versioning-apps" }, ], }, ], diff --git a/site/guide/advance/decisions.md b/site/guide/advanced/decisions.md similarity index 100% rename from site/guide/advance/decisions.md rename to site/guide/advanced/decisions.md diff --git a/site/guide/advance/experimental-options.md b/site/guide/advanced/experimental-options.md similarity index 100% rename from site/guide/advance/experimental-options.md rename to site/guide/advanced/experimental-options.md diff --git a/site/guide/advance/fixed-packages.md b/site/guide/advanced/fixed-packages.md similarity index 100% rename from site/guide/advance/fixed-packages.md rename to site/guide/advanced/fixed-packages.md diff --git a/site/guide/advance/linked-packages.md b/site/guide/advanced/linked-packages.md similarity index 100% rename from site/guide/advance/linked-packages.md rename to site/guide/advanced/linked-packages.md diff --git a/site/guide/advance/modifying-changelog-format.md b/site/guide/advanced/modifying-changelog-format.md similarity index 100% rename from site/guide/advance/modifying-changelog-format.md rename to site/guide/advanced/modifying-changelog-format.md diff --git a/site/guide/advance/prereleases.md b/site/guide/advanced/prereleases.md similarity index 100% rename from site/guide/advance/prereleases.md rename to site/guide/advanced/prereleases.md diff --git a/site/faq/publishing-in-monorepos.md b/site/guide/advanced/publishing-in-monorepos.md similarity index 100% rename from site/faq/publishing-in-monorepos.md rename to site/guide/advanced/publishing-in-monorepos.md diff --git a/site/guide/advance/snapshot-releases.md b/site/guide/advanced/snapshot-releases.md similarity index 95% rename from site/guide/advance/snapshot-releases.md rename to site/guide/advanced/snapshot-releases.md index 6c5ada30d..30013dac0 100644 --- a/site/guide/advance/snapshot-releases.md +++ b/site/guide/advanced/snapshot-releases.md @@ -4,7 +4,7 @@ Snapshot releases are a way to release your changes for testing without updating ## Starting Off -Create changesets as normal, as described in [adding a changeset](../../guide/basic/adding-a-changeset.md). When you are ready to release a snapshot, you should make a dedicated branch for doing so. +Create changesets as normal, as described in [adding a changeset](../basic/adding-a-changeset.md). When you are ready to release a snapshot, you should make a dedicated branch for doing so. ## Versioning your packages diff --git a/site/guide/advance/versioning-apps.md b/site/guide/advanced/versioning-apps.md similarity index 100% rename from site/guide/advance/versioning-apps.md rename to site/guide/advanced/versioning-apps.md diff --git a/site/guide/basic/adding-a-changeset.md b/site/guide/basic/adding-a-changeset.md index 8108f45c3..031d9e486 100644 --- a/site/guide/basic/adding-a-changeset.md +++ b/site/guide/basic/adding-a-changeset.md @@ -68,4 +68,4 @@ Changesets are designed to stack, so there's no problem with adding multiple. Yo ## I want to know more about changesets -[here is a more in-depth explanation](../intro/concepts.md) +[here is a more in-depth explanation](../introduction/concepts.md) diff --git a/site/guide/api/cli.md b/site/guide/basic/cli.md similarity index 95% rename from site/guide/api/cli.md rename to site/guide/basic/cli.md index 1bb036610..00906945b 100644 --- a/site/guide/api/cli.md +++ b/site/guide/basic/cli.md @@ -1,6 +1,6 @@ # Command line options -The command line for changesets is the main way of interacting with it. There are 4 main commands. If you are looking for how we recommend you setup and manage changesets with the commands, check out our [intro to using changesets](../intro/getting-started.md) +The command line for changesets is the main way of interacting with it. There are 4 main commands. If you are looking for how we recommend you setup and manage changesets with the commands, check out our [intro to using changesets](../introduction/getting-started.md) - `init` - `add [--empty] [--open] [--since ] [--message ]` @@ -94,13 +94,13 @@ This command is used to allow you to skip packages from being published. This al 1. If the package is mentioned in a changeset that also includes a package that is not ignored, publishing will fail. 2. If the package requires one of its dependencies to be updated as part of a publish. -These restrictions exist to ensure your repository or published code does not end up in a broken state. For additional information on the intricacies of publishing, check out our guide on [problems publishing in monorepos](../../faq/publishing-in-monorepos.md). +These restrictions exist to ensure your repository or published code does not end up in a broken state. For additional information on the intricacies of publishing, check out our guide on [problems publishing in monorepos](../advanced/publishing-in-monorepos.md). ``` changeset version --snapshot ``` -Snapshot is used for a special kind of publishing for testing - it creates temporary versions with a tag, instead of updating versions from the current semver ranges. You should not use this without [reading the documentation on snapshot releases](../advance/snapshot-releases.md) +Snapshot is used for a special kind of publishing for testing - it creates temporary versions with a tag, instead of updating versions from the current semver ranges. You should not use this without [reading the documentation on snapshot releases](../advanced/snapshot-releases.md) ## publish @@ -114,7 +114,7 @@ Because this command assumes that the last commit is the release commit, you sho `--otp={token}` - allows you to provide an npm one-time password if you have auth and writes enabled on npm. The CLI also prompts for the OTP if it's not provided with the --otp option. -`--tag TAGNAME` - for packages that are published, the chosen tag will be used instead of `latest`, allowing you to publish changes intended for testing and validation, not main consumption. This will most likely be used with [snapshot releases](../advance/snapshot-releases.md). +`--tag TAGNAME` - for packages that are published, the chosen tag will be used instead of `latest`, allowing you to publish changes intended for testing and validation, not main consumption. This will most likely be used with [snapshot releases](../advanced/snapshot-releases.md). ### Git Tags @@ -148,7 +148,7 @@ changeset pre [exit|enter {tag}] The pre command enters and exits pre mode. The command does not do any actual versioning, when doing a pre-release, you should run changeset pre enter next(or a different tag, the tag is what is in versions and is the npm dist tag) and then do the normal release process with changeset version and changeset publish. For more information about the pre command, see the prereleases [the prereleases documentation](https://github.com/changesets/changesets/blob/master/docs/prereleases.md). -> NOTE: pre-releases are a very complicated feature. Many of the safety rails that changesets helps you with will be taken off. We recommend that you read both [problems publishing in monorepos](../../faq/publishing-in-monorepos.md) and be clear on both exiting and entering pre-releases before using it. You may also prefer using [snapshot releases](../advance/snapshot-releases.md) for a slightly less involved process. +> NOTE: pre-releases are a very complicated feature. Many of the safety rails that changesets helps you with will be taken off. We recommend that you read both [problems publishing in monorepos](../advanced/publishing-in-monorepos.md) and be clear on both exiting and entering pre-releases before using it. You may also prefer using [snapshot releases](../advanced/snapshot-releases.md) for a slightly less involved process. ## tag diff --git a/site/guide/basic/configuration.md b/site/guide/basic/configuration.md index ff8dc363e..e69119d4c 100644 --- a/site/guide/basic/configuration.md +++ b/site/guide/basic/configuration.md @@ -77,7 +77,7 @@ There are two caveats to this. 1. If the package is mentioned in a changeset that also includes a package that is not ignored, publishing will fail. 2. If the package requires one of its dependencies to be updated as part of a publish. -These restrictions exist to ensure your repository or published code do not end up in a broken state. For a more detailed intricacies of publishing, check out our guide on [problems publishing in monorepos](../../faq/publishing-in-monorepos.md). +These restrictions exist to ensure your repository or published code do not end up in a broken state. For a more detailed intricacies of publishing, check out our guide on [problems publishing in monorepos](../advanced/publishing-in-monorepos.md). > [!TIP] > You can also provide glob expressions to match the packages, according to the [micromatch](https://www.npmjs.com/package/micromatch) format. @@ -92,7 +92,7 @@ This option can be used to declare that packages should be version-bumped and pu } ``` -If you want to use this option, you should read the documentation on [fixed packages](../advance/fixed-packages.md) to fully understand the implementation and implications. +If you want to use this option, you should read the documentation on [fixed packages](../advanced/fixed-packages.md) to fully understand the implementation and implications. ## `linked` (array of arrays of package names) @@ -104,7 +104,7 @@ This option can be used to declare that packages should 'share' a version, inste } ``` -If you want to use this option, you should read the documentation on [linked packages](../advance/linked-packages.md) to fully understand the implementation and implications. +If you want to use this option, you should read the documentation on [linked packages](../advanced/linked-packages.md) to fully understand the implementation and implications. > [!WARNING] > This does not do what some other tools do, which is make sure when any package is published, all other packages are also published with the same version. @@ -169,7 +169,7 @@ You would specify our github changelog generator with: If you want to disable thank you messages, add `"disableThanks": true` to the options. -For more details on these functions and information on how to write your own see [changelog-functions](../advance/modifying-changelog-format.md) +For more details on these functions and information on how to write your own see [changelog-functions](../advanced/modifying-changelog-format.md) ## `bumpVersionsWithWorkspaceProtocolOnly` (optional boolean) diff --git a/site/faq/common-questions.md b/site/guide/introduction/common-questions.md similarity index 100% rename from site/faq/common-questions.md rename to site/guide/introduction/common-questions.md diff --git a/site/guide/intro/concepts.md b/site/guide/introduction/concepts.md similarity index 100% rename from site/guide/intro/concepts.md rename to site/guide/introduction/concepts.md diff --git a/site/guide/intro/dictionary.md b/site/guide/introduction/dictionary.md similarity index 95% rename from site/guide/intro/dictionary.md rename to site/guide/introduction/dictionary.md index 2e3dd67f9..3872915ba 100644 --- a/site/guide/intro/dictionary.md +++ b/site/guide/introduction/dictionary.md @@ -16,8 +16,8 @@ Several of these have associated type definitions, which you can find in [our ty - **single-package repo** - A repository which only contains a single package which is at the root of the repo - **multi-package repo/monorepo** - A repository which contains multiple packages, generally managed by [Bolt](https://github.com/boltpkg/bolt) or [Yarn Workspaces](https://yarnpkg.com/lang/en/docs/workspaces/). - **release line generators** - The `getReleaseLine` and `getDependencyReleaseLine` functions which are responsible for creating the lines inserted into changelog. A changelog entry for a particular release can be thought of as `releaseLineGenerators(changesets)` -- **fixed packages** - Fixed packages share a semver categorisation, such that all fixed packages have the same semver version and are always published together. The logistics of this are best left to our [fixed-packages](../advance/fixed-packages.md) documentation. -- **linked packages** - Linked packages share a semver categorisation, such that all published linked packages have consistent new semver ranges. The logistics of this are best left to our [linked-packages](../advance/linked-packages.md) documentation. +- **fixed packages** - Fixed packages share a semver categorisation, such that all fixed packages have the same semver version and are always published together. The logistics of this are best left to our [fixed-packages](../advanced/fixed-packages.md) documentation. +- **linked packages** - Linked packages share a semver categorisation, such that all published linked packages have consistent new semver ranges. The logistics of this are best left to our [linked-packages](../advanced/linked-packages.md) documentation. - **release instruction** An object containing an intent to release a single package, consisting of the package name and a bump type - **release plan** - A calculated object that shows everything a collection of changesets will release, and at what version, and how. This object includes a calculation of dependencies, and considerations for `linked` packages. - **absolutely correct semver** - making semver versioning decisions to ensure nothing less than major is capable of breaking a consumer's code. Because literally any change is technically capable of breaking a user's code, absolutely correct semver requires that all changes are major changes. @@ -25,7 +25,7 @@ Several of these have associated type definitions, which you can find in [our ty - **dependency** - A package that is depended upon by another given package. - **dependent** - A package which depends on another given package. This is frequently used in the context of getting the dependents of a package so they can be released. - **release** - The combination of versioning and publishing a package or packages which may include a build process before publishing -- **prereleases** - A pre-release is a release that uses a tag, and is not published as `latest` on npm. This is designed for when you want to share code, but are not yet ready for it to be the main package used by everyone. Pre-releases for packages are common, but pre-releases within a monorepo presents unique problems. You can see our exhaustive pre-release documentation [in our prereleases documentation](../advance/prereleases.md). In addition, there are two different approaches to pre-releases which are defined for use separately. +- **prereleases** - A pre-release is a release that uses a tag, and is not published as `latest` on npm. This is designed for when you want to share code, but are not yet ready for it to be the main package used by everyone. Pre-releases for packages are common, but pre-releases within a monorepo presents unique problems. You can see our exhaustive pre-release documentation [in our prereleases documentation](../advanced/prereleases.md). In addition, there are two different approaches to pre-releases which are defined for use separately. - **Release Candidate (RC) prerelease** - An RC prerelease is done before an intended important release, likely a major release. It includes semver information about what the next intended release version is, a tag, and an iterated number for the prerelease. The output of this is intended to be committed, and then further work done on the branch. An example would be if I am on `1.0.0` of a package, and I want to do an RC for the next `major` version we would have: `package-one@2.0.0-my-tag.0`, and then the next publish is `package-one@2.0.0-my-tag.1`. - **snapshot prerelease** - A snapshot pre-release is intended to make it easy to test all changes at a particular git commit. It is published at `0.0.0` and uses the git hash as the tag. This should be used as a less formal method than a release candidate to make it easy to install and test changes. An example, if we have a package at `1.0.0`, and have a changeset for it to be `major` bumped, a snapshot release will be at `0.0.0-ABCDEFGH` (the last github hash). If we add more commits, the next snapshot would be `0.0.0-HIJKLMNOP`. diff --git a/site/guide/intro/getting-started.md b/site/guide/introduction/getting-started.md similarity index 100% rename from site/guide/intro/getting-started.md rename to site/guide/introduction/getting-started.md diff --git a/site/guide/intro/what-are-changesets.md b/site/guide/introduction/what-are-changesets.md similarity index 92% rename from site/guide/intro/what-are-changesets.md rename to site/guide/introduction/what-are-changesets.md index cb82aefcc..fe3863e98 100644 --- a/site/guide/intro/what-are-changesets.md +++ b/site/guide/introduction/what-are-changesets.md @@ -7,7 +7,7 @@ The changesets workflow is designed to help when people are making changes, all Changesets has a focus on solving these problems for multi-package repositories, and keeps packages that rely on each other within the multi-package repository up-to-date, as well as making it easy to make changes to groups of packages. > [!NOTE] -> Just want to try it out? Skip to the [Getting Started](/guide/intro/getting-started) page. +> Just want to try it out? Skip to the [Getting Started](./getting-started.md) page. ## How do we do that? diff --git a/site/index.md b/site/index.md index 2fda4396d..c2a5ac08f 100644 --- a/site/index.md +++ b/site/index.md @@ -12,7 +12,7 @@ hero: actions: - theme: brand text: Get Started - link: /guide/intro/what-are-changesets + link: ./guide/introduction/getting-started.md - theme: alt text: View on GitHub link: https://github.com/changesets/changesets From 4f8ae0bd45fcff22d7a7ad2f0b0e1be880a3eda4 Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 6 May 2026 11:34:20 +0800 Subject: [PATCH 06/80] Improve code blocks --- .../advanced/modifying-changelog-format.md | 16 +- site/guide/advanced/prereleases.md | 232 +++++++++++++++--- site/guide/advanced/snapshot-releases.md | 64 ++++- site/guide/basic/automating-changesets.md | 16 +- site/guide/introduction/getting-started.md | 64 +++-- 5 files changed, 324 insertions(+), 68 deletions(-) diff --git a/site/guide/advanced/modifying-changelog-format.md b/site/guide/advanced/modifying-changelog-format.md index 9b48f54c8..a5587ea31 100644 --- a/site/guide/advanced/modifying-changelog-format.md +++ b/site/guide/advanced/modifying-changelog-format.md @@ -8,10 +8,22 @@ To change how the changelog is generated, you use the `changelog` setting in the For example, `changesets` has a package, `@changesets/changelog-git`. To use it, you would first need to install the package. -```bash -yarn add @changesets/changelog-git +::: code-group + +```bash [npm] +$ npm install @changesets/changelog-git +``` + +```bash [pnpm] +$ pnpm add @changesets/changelog-git ``` +```bash [yarn] +$ yarn add @changesets/changelog-git +``` + +::: + Next, change your `.changeset/config.json` to point to the new package: ``` diff --git a/site/guide/advanced/prereleases.md b/site/guide/advanced/prereleases.md index d53649b22..1251af212 100644 --- a/site/guide/advanced/prereleases.md +++ b/site/guide/advanced/prereleases.md @@ -12,15 +12,37 @@ When you want to do a prerelease, you need to enter prerelease mode. You can do A prerelease workflow might look something like this: -```bash -yarn changeset pre enter next -yarn changeset version -git add . -git commit -m "Enter prerelease mode and version packages" -yarn changeset publish -git push --follow-tags +::: code-group + +```bash [npm] +$ npx @changesets/cli pre enter next +$ npx @changesets/cli version +$ git add . +$ git commit -m "Enter prerelease mode and version packages" +$ npx @changesets/cli publish +$ git push --follow-tags ``` +```bash [pnpm] +$ pnpm changeset pre enter next +$ pnpm changeset version +$ git add . +$ git commit -m "Enter prerelease mode and version packages" +$ pnpm changeset publish +$ git push --follow-tags +``` + +```bash [yarn] +$ yarn changeset pre enter next +$ yarn changeset version +$ git add . +$ git commit -m "Enter prerelease mode and version packages" +$ yarn changeset publish +$ git push --follow-tags +``` + +::: + Let's go through what's happening here. For this example, let's say you have a repo that looks like this: ``` @@ -32,16 +54,40 @@ packages/ pkg-b@minor ``` -```bash -yarn changeset pre enter next +::: code-group + +```bash [npm] +$ npx @changesets/cli pre enter next +``` + +```bash [pnpm] +$ pnpm changeset pre enter next ``` +```bash [yarn] +$ yarn changeset pre enter next +``` + +::: + This command changes Changesets into prerelease mode which creates a `pre.json` file in the `.changeset` directory which stores information about the state the prerelease is in. For the specific data stored in the `pre.json` file, see the type definition of `PreState` in [`@changesets/types`](https://github.com/changesets/changesets/tree/main/packages/types). -```bash -yarn changeset version +::: code-group + +```bash [npm] +$ npx @changesets/cli version +``` + +```bash [pnpm] +$ pnpm changeset version +``` + +```bash [yarn] +$ yarn changeset version ``` +::: + This command will version packages as you would normally expect but append `-next.0`. An important note is that this will bump dependent packages that wouldn't be bumped in normal releases because prerelease versions are not satisfied by most semver ranges.(e.g. `^5.0.0` is not satisfied by `5.1.0-next.0`) The repo would now look like this: @@ -54,22 +100,54 @@ packages/ .changeset/ ``` -```bash -yarn changeset publish +::: code-group + +```bash [npm] +$ npx @changesets/cli publish +``` + +```bash [pnpm] +$ pnpm changeset publish +``` + +```bash [yarn] +$ yarn changeset publish ``` +::: + This command will publish to npm as the publish command normally does though it will set the dist tag to the tag you specified when running the prerelease command. When you want to do another prerelease, your workflow would look something like this: -```bash -yarn changeset version -git add . -git commit -m "Version packages" -yarn changeset publish -git push --follow-tags +::: code-group + +```bash [npm] +$ npx @changesets/cli version +$ git add . +$ git commit -m "Version packages" +$ npx @changesets/cli publish +$ git push --follow-tags +``` + +```bash [pnpm] +$ pnpm changeset version +$ git add . +$ git commit -m "Version packages" +$ pnpm changeset publish +$ git push --follow-tags +``` + +```bash [yarn] +$ yarn changeset version +$ git add . +$ git commit -m "Version packages" +$ yarn changeset publish +$ git push --follow-tags ``` +::: + Let's say we add some changesets and a new package so our repo looks like this ``` @@ -85,10 +163,22 @@ packages/ pkg-d@major ``` -```bash -yarn changeset version +::: code-group + +```bash [npm] +$ npx @changesets/cli version +``` + +```bash [pnpm] +$ pnpm changeset version ``` +```bash [yarn] +$ yarn changeset version +``` + +::: + The version command will behave just like it does for the first versioning of a prerelease except the number at the end will be updated. The repo would now look like this: ``` @@ -99,33 +189,91 @@ packages/ pkg-d@1.0.0-next.0 has no deps ``` -```bash -yarn changeset publish +::: code-group + +```bash [npm] +$ npx @changesets/cli publish +``` + +```bash [pnpm] +$ pnpm changeset publish +``` + +```bash [yarn] +$ yarn changeset publish ``` +::: + This command will publish to npm just like it does for the first prerelease except because we're adding a new package(we need to define this, is it new to the repo or new to npm? I'm thinking new to npm), the new package will be published with the `latest` dist tag rather than the `next` tag because it's the first time it's being published which means it will be on `latest` anyway. For future publishes until pkg-d is out of prerelease, it will also be published to `latest`. When you're ready to do the final release, your workflow would look something like this: -```bash -yarn changeset pre exit -yarn changeset version -git add . -git commit -m "Exit prerelease mode and version packages" -yarn changeset publish -git push --follow-tags +::: code-group + +```bash [npm] +$ npx @changesets/cli pre exit +$ npx @changesets/cli version +$ git add . +$ git commit -m "Exit prerelease mode and version packages" +$ npx @changesets/cli publish +$ git push --follow-tags +``` + +```bash [pnpm] +$ pnpm changeset pre exit +$ pnpm changeset version +$ git add . +$ git commit -m "Exit prerelease mode and version packages" +$ pnpm changeset publish +$ git push --follow-tags +``` + +```bash [yarn] +$ yarn changeset pre exit +$ yarn changeset version +$ git add . +$ git commit -m "Exit prerelease mode and version packages" +$ yarn changeset publish +$ git push --follow-tags +``` + +::: + +::: code-group + +```bash [npm] +$ npx @changesets/cli pre exit +``` + +```bash [pnpm] +$ pnpm changeset pre exit ``` -```bash -yarn changeset pre exit +```bash [yarn] +$ yarn changeset pre exit ``` +::: + This command will set an intent to exit prerelease mode in the `pre.json` file though it won't do any actual versioning. -```bash -yarn changeset version +::: code-group + +```bash [npm] +$ npx @changesets/cli version +``` + +```bash [pnpm] +$ pnpm changeset version +``` + +```bash [yarn] +$ yarn changeset version ``` +::: + The version command will apply any changesets currently in the repo and then remove the prerelease tag from the versions. The repo would now look like this: ``` @@ -136,8 +284,20 @@ packages/ pkg-d@1.0.0 has no deps ``` -```bash -yarn changeset publish +::: code-group + +```bash [npm] +$ npx @changesets/cli publish +``` + +```bash [pnpm] +$ pnpm changeset publish +``` + +```bash [yarn] +$ yarn changeset publish ``` +::: + The publish command will publish everything to the `latest` dist tag as normal. diff --git a/site/guide/advanced/snapshot-releases.md b/site/guide/advanced/snapshot-releases.md index 30013dac0..cbce2edb8 100644 --- a/site/guide/advanced/snapshot-releases.md +++ b/site/guide/advanced/snapshot-releases.md @@ -8,18 +8,42 @@ Create changesets as normal, as described in [adding a changeset](../basic/addin ## Versioning your packages -```bash -yarn changeset version --snapshot +::: code-group + +```bash [npm] +$ npx @changesets/cli version --snapshot +``` + +```bash [pnpm] +$ pnpm changeset version --snapshot ``` +```bash [yarn] +$ yarn changeset version --snapshot +``` + +::: + This will apply the changesets, but instead of using the next version, all versions will be set to `0.0.0-THE_TIME_YOU_DID_THIS`. If you want to add a personalised part to this version number, such as `bulbasaur`, you can run -```bash -yarn changeset version --snapshot bulbasaur +::: code-group + +```bash [npm] +$ npx @changesets/cli version --snapshot bulbasaur +``` + +```bash [pnpm] +$ pnpm changeset version --snapshot bulbasaur ``` +```bash [yarn] +$ yarn changeset version --snapshot bulbasaur +``` + +::: + This will instead update versions to `0.0.0-bulbasaur-THE_TIME_YOU_DID_THIS` ## Publishing your packages @@ -38,16 +62,40 @@ When you want to get people to test your snapshots, they can either update their For our above example, you could run -```bash -yarn add your-package-name@0.0.0-bulbasaur-THE_TIME_YOU_DID_THIS +::: code-group + +```bash [npm] +$ npm install your-package-name@0.0.0-bulbasaur-THE_TIME_YOU_DID_THIS +``` + +```bash [pnpm] +$ pnpm add your-package-name@0.0.0-bulbasaur-THE_TIME_YOU_DID_THIS ``` +```bash [yarn] +$ yarn add your-package-name@0.0.0-bulbasaur-THE_TIME_YOU_DID_THIS +``` + +::: + or the tag: -```bash -yarn add your-package-name@bulbasaur +::: code-group + +```bash [npm] +$ npm install your-package-name@bulbasaur +``` + +```bash [pnpm] +$ pnpm add your-package-name@bulbasaur ``` +```bash [yarn] +$ yarn add your-package-name@bulbasaur +``` + +::: + ## What to do with the snapshot branch In almost all circumstances, we recommend that the changes after you have run `version` get merged back into your main branch. With snapshots, this is not the case. We recommend that you do not push the changes from this running of `version` to any branch. This is because the snapshot is intended for installation only, not to represent the correct published state of the repo. Save the generated version, and the tag you used, but do not push this to a branch you are planning to merge into the main branch, or merge it into the main branch. diff --git a/site/guide/basic/automating-changesets.md b/site/guide/basic/automating-changesets.md index 8a88c6d11..51d573f75 100644 --- a/site/guide/basic/automating-changesets.md +++ b/site/guide/basic/automating-changesets.md @@ -28,10 +28,22 @@ Sometimes, you may want to make CI fail if no changeset is present to ensure no In your CI process, add a step that runs: -```bash -changeset status --since=main +::: code-group + +```bash [npm] +$ npx @changesets/cli status --since=main +``` + +```bash [pnpm] +$ pnpm changeset status --since=main ``` +```bash [yarn] +$ yarn changeset status --since=main +``` + +::: + This will exit with exit code 1 if there have been no new changesets since main. In some cases, you may _want_ to merge a change without doing any releases (such as when you only change tests or build tools). In this case, you can run `changeset --empty`. This will add a special changeset that does not release anything. diff --git a/site/guide/introduction/getting-started.md b/site/guide/introduction/getting-started.md index b02a8c4cb..3ab84a5bb 100644 --- a/site/guide/introduction/getting-started.md +++ b/site/guide/introduction/getting-started.md @@ -16,58 +16,82 @@ The second two steps can be made part of a CI process. ## Add the changeset tool -```shell -yarn add -D @changesets/cli && yarn changeset init +::: code-group + +```bash [npm] +$ npm install --save-dev @changesets/cli && npx @changesets/cli init ``` -or +```bash [pnpm] +$ pnpm add -D @changesets/cli && pnpm changeset init +``` -```shell -npx @changesets/cli init +```bash [yarn] +$ yarn add -D @changesets/cli && yarn changeset init ``` +::: + ## Adding changesets -```shell -yarn changeset +::: code-group + +```bash [npm] +$ npx @changesets/cli ``` -or +```bash [pnpm] +$ pnpm changeset +``` -```shell -npx @changesets/cli +```bash [yarn] +$ yarn changeset ``` +::: + > Note: You can run `changeset add` to add a changeset if you want to, but running Changesets without any command works as well. ## Versioning and publishing Once you decide you want to do a release, you can run -```shell -yarn changeset version +::: code-group + +```bash [npm] +$ npx @changesets/cli version ``` -or +```bash [pnpm] +$ pnpm changeset version +``` -```shell -npx @changesets/cli version +```bash [yarn] +$ yarn changeset version ``` +::: + This consumes all changesets, and updates to the most appropriate semver version based on those changesets. It also writes changelog entries for each consumed changeset. We recommend at this step reviewing both the changelog entries and the version changes for packages. Once you are confident that these are correct, and have made any necessary tweaks to changelogs, you can publish your packages: -```shell -yarn changeset publish +::: code-group + +```bash [npm] +$ npx @changesets/cli publish ``` -or +```bash [pnpm] +$ pnpm changeset publish +``` -```shell -npx @changesets/cli publish +```bash [yarn] +$ yarn changeset publish ``` +::: + This will run npm publish in each package that is of a later version than the one currently listed on npm. ## Some handy advice From ddb88d94e5ef3cc9a5277f877caf32267a54b65e Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 6 May 2026 14:24:55 +0800 Subject: [PATCH 07/80] Add group icons --- pnpm-lock.yaml | 79 ++++++++++++ site/.vitepress/config.ts | 14 ++- site/.vitepress/theme/index.ts | 2 +- site/.vitepress/theme/style.css | 138 --------------------- site/guide/advanced/decisions.md | 3 +- site/guide/basic/cli.md | 6 +- site/guide/introduction/getting-started.md | 3 +- site/package.json | 3 +- 8 files changed, 102 insertions(+), 146 deletions(-) delete mode 100644 site/.vitepress/theme/style.css diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 982de3de6..74f31afa3 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -542,9 +542,15 @@ importers: vitepress: specifier: ^2.0.0-alpha.17 version: 2.0.0-alpha.17(@types/node@24.12.2)(oxc-minify@0.128.0)(postcss@8.5.13)(terser@5.44.1)(typescript@6.0.3) + vitepress-plugin-group-icons: + specifier: ^1.7.5 + version: 1.7.5(vite@8.0.10) packages: + '@antfu/install-pkg@1.1.0': + resolution: {integrity: sha512-MGQsmw10ZyI+EJo45CdSER4zEb+p31LpDAFp2Z3gkSd1yqVZGi0Ebx++YTEMonJy4oChEMLsxZ64j8FH6sSqtQ==} + '@babel/code-frame@7.27.1': resolution: {integrity: sha512-cjQ7ZlQ0Mv3b47hABuTevyTuYN4i+loJKGeV9flcCgIK37cCXRh+L1bd3iBHlynerhQ7BhCkn2BPbQUL+rGqFg==} engines: {node: '>=6.9.0'} @@ -1139,12 +1145,21 @@ packages: resolution: {integrity: sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==} engines: {node: '>=18.18'} + '@iconify-json/logos@1.2.11': + resolution: {integrity: sha512-fOo4pGEatuyuCFNL+cwquYMa2Im0oJHRHV7lt/Qqs5Ode/lPImHCQcfTtPzZj7qYMPb/h8YHN3TG54uEowrjNQ==} + '@iconify-json/simple-icons@1.2.80': resolution: {integrity: sha512-iglncJJ6X/dVuzFDU32MrHwwo4RBwivGf108dgyYg+HKS78ifx0h7sTenpDZMVT+UhdS6CSgZcvY/SvRXlIEUg==} + '@iconify-json/vscode-icons@1.2.48': + resolution: {integrity: sha512-343rDF9S3G4hB9k/5jJz3EzrNxwY4L086eNQ0LCPiqisPub8Q5lrPu+DOE2MtRaYA80JlF0GJWN7H1XVNeEkSQ==} + '@iconify/types@2.0.0': resolution: {integrity: sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg==} + '@iconify/utils@3.1.1': + resolution: {integrity: sha512-MwzoDtw9rO1x+qfgLTV/IVXsHDBqeYZoMIQC8SfxfYSlaSUG+oWiAcoiB1yajAda6mqblm4/1/w2E8tRu7a7Tw==} + '@inquirer/external-editor@1.0.3': resolution: {integrity: sha512-RWbSrDiYmO4LbejWY7ttpxczuwQyZLBUyygsA9Nsv95hpzUWwnNTVQmAq3xuh7vNwCp07UTmE5i11XAEExx4RA==} engines: {node: '>=18'} @@ -1951,6 +1966,9 @@ packages: concat-map@0.0.1: resolution: {integrity: sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==} + confbox@0.1.8: + resolution: {integrity: sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==} + config-chain@1.1.13: resolution: {integrity: sha512-qj+f8APARXHrM0hraqXYb2/bOVSV4PvJQlNZ/DVj0QrmNM2q2euizkeuVckQ57J+W0mRH6Hvi+k50M4Jul2VRQ==} @@ -2619,6 +2637,9 @@ packages: minisearch@7.2.0: resolution: {integrity: sha512-dqT2XBYUOZOiC5t2HRnwADjhNS2cecp9u+TJRiJ1Qp/f5qjkeT5APcGPjHw+bz89Ms8Jp+cG4AlE+QZ/QnDglg==} + mlly@1.8.2: + resolution: {integrity: sha512-d+ObxMQFmbt10sretNDytwt85VrbkhhUA/JBGm1MPaWJ65Cl4wOgLaB1NYvJSZ0Ef03MMEU/0xpPMXUIQ29UfA==} + mri@1.2.0: resolution: {integrity: sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==} engines: {node: '>=4'} @@ -2750,6 +2771,9 @@ packages: resolution: {integrity: sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==} engines: {node: '>= 6'} + pkg-types@1.3.1: + resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==} + postcss@8.5.13: resolution: {integrity: sha512-qif0+jGGZoLWdHey3UFHHWP0H7Gbmsk8T5VEqyYFbWqPr1XqvLGBbk/sl8V5exGmcYJklJOhOQq1pV9IcsiFag==} engines: {node: ^10 || ^12 || >=14} @@ -2995,6 +3019,9 @@ packages: engines: {node: '>=14.17'} hasBin: true + ufo@1.6.4: + resolution: {integrity: sha512-JFNbkD1Svwe0KvGi8GOeLcP4kAWQ609twvCdcHxq1oSL8svv39ZuSvajcD8B+5D0eL4+s1Is2D/O6KN3qcTeRA==} + undici-types@7.16.0: resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==} @@ -3098,6 +3125,14 @@ packages: yaml: optional: true + vitepress-plugin-group-icons@1.7.5: + resolution: {integrity: sha512-QzcroUuIiVKyXpmEiiHVbfRTQIy9Zbwxpk5JC/zavO8mavitwumz2RZWlwTchMCCHducYyPptkYvXvdnNUWkog==} + peerDependencies: + vite: '>=3' + peerDependenciesMeta: + vite: + optional: true + vitepress@2.0.0-alpha.17: resolution: {integrity: sha512-Z3VPUpwk/bHYqt1uMVOOK1/4xFiWQov1GNc2FvMdz6kvje4JRXEOngVI9C+bi5jeedMSHiA4dwKkff1NCvbZ9Q==} hasBin: true @@ -3198,6 +3233,11 @@ packages: snapshots: + '@antfu/install-pkg@1.1.0': + dependencies: + package-manager-detector: 1.6.0 + tinyexec: 1.0.2 + '@babel/code-frame@7.27.1': dependencies: '@babel/helper-validator-identifier': 7.28.5 @@ -3954,12 +3994,26 @@ snapshots: '@humanwhocodes/retry@0.4.3': {} + '@iconify-json/logos@1.2.11': + dependencies: + '@iconify/types': 2.0.0 + '@iconify-json/simple-icons@1.2.80': dependencies: '@iconify/types': 2.0.0 + '@iconify-json/vscode-icons@1.2.48': + dependencies: + '@iconify/types': 2.0.0 + '@iconify/types@2.0.0': {} + '@iconify/utils@3.1.1': + dependencies: + '@antfu/install-pkg': 1.1.0 + '@iconify/types': 2.0.0 + mlly: 1.8.2 + '@inquirer/external-editor@1.0.3(@types/node@24.12.2)': dependencies: chardet: 2.1.1 @@ -4762,6 +4816,8 @@ snapshots: concat-map@0.0.1: {} + confbox@0.1.8: {} + config-chain@1.1.13: dependencies: ini: 1.3.8 @@ -5486,6 +5542,13 @@ snapshots: minisearch@7.2.0: {} + mlly@1.8.2: + dependencies: + acorn: 8.16.0 + pathe: 2.0.3 + pkg-types: 1.3.1 + ufo: 1.6.4 + mri@1.2.0: {} ms@2.1.3: {} @@ -5624,6 +5687,12 @@ snapshots: pirates@4.0.7: {} + pkg-types@1.3.1: + dependencies: + confbox: 0.1.8 + mlly: 1.8.2 + pathe: 2.0.3 + postcss@8.5.13: dependencies: nanoid: 3.3.11 @@ -5857,6 +5926,8 @@ snapshots: typescript@6.0.3: {} + ufo@1.6.4: {} + undici-types@7.16.0: {} unicode-canonical-property-names-ecmascript@2.0.1: {} @@ -5931,6 +6002,14 @@ snapshots: fsevents: 2.3.3 terser: 5.44.1 + vitepress-plugin-group-icons@1.7.5(vite@8.0.10): + dependencies: + '@iconify-json/logos': 1.2.11 + '@iconify-json/vscode-icons': 1.2.48 + '@iconify/utils': 3.1.1 + optionalDependencies: + vite: 8.0.10(@types/node@24.12.2)(terser@5.44.1) + vitepress@2.0.0-alpha.17(@types/node@24.12.2)(oxc-minify@0.128.0)(postcss@8.5.13)(terser@5.44.1)(typescript@6.0.3): dependencies: '@docsearch/css': 4.6.3 diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts index 2955ce163..ee15e7f4f 100644 --- a/site/.vitepress/config.ts +++ b/site/.vitepress/config.ts @@ -1,4 +1,8 @@ import { defineConfig } from "vitepress"; +import { + groupIconMdPlugin, + groupIconVitePlugin, +} from "vitepress-plugin-group-icons"; import packageJson from "../../packages/cli/package.json" with { type: "json" }; const changesetsVersion = packageJson.version; @@ -6,10 +10,16 @@ const changesetsVersion = packageJson.version; export default defineConfig({ title: "Changesets", head: [["link", { rel: "icon", href: "logo.svg" }]], - lastUpdated: true, cleanUrls: true, - + markdown: { + config(md) { + md.use(groupIconMdPlugin); + }, + }, + vite: { + plugins: [groupIconVitePlugin()], + }, themeConfig: { logo: { light: "/logo-light.svg", diff --git a/site/.vitepress/theme/index.ts b/site/.vitepress/theme/index.ts index 91ff50b15..2888ebae4 100644 --- a/site/.vitepress/theme/index.ts +++ b/site/.vitepress/theme/index.ts @@ -1,5 +1,5 @@ import DefaultTheme from "vitepress/theme"; -// import "./style.css"; import "./custom.css"; +import "virtual:group-icons.css"; export default DefaultTheme; diff --git a/site/.vitepress/theme/style.css b/site/.vitepress/theme/style.css deleted file mode 100644 index 8702981dd..000000000 --- a/site/.vitepress/theme/style.css +++ /dev/null @@ -1,138 +0,0 @@ -/** - * Customize default theme styling by overriding CSS variables: - * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css - */ - -/** - * Colors - * - * Each colors have exact same color scale system with 3 levels of solid - * colors with different brightness, and 1 soft color. - * - * - `XXX-1`: The most solid color used mainly for colored text. It must - * satisfy the contrast ratio against when used on top of `XXX-soft`. - * - * - `XXX-2`: The color used mainly for hover state of the button. - * - * - `XXX-3`: The color for solid background, such as bg color of the button. - * It must satisfy the contrast ratio with pure white (#ffffff) text on - * top of it. - * - * - `XXX-soft`: The color used for subtle background such as custom container - * or badges. It must satisfy the contrast ratio when putting `XXX-1` colors - * on top of it. - * - * The soft color must be semi transparent alpha channel. This is crucial - * because it allows adding multiple "soft" colors on top of each other - * to create a accent, such as when having inline code block inside - * custom containers. - * - * - `default`: The color used purely for subtle indication without any - * special meanings attached to it such as bg color for menu hover state. - * - * - `brand`: Used for primary brand colors, such as link text, button with - * brand theme, etc. - * - * - `tip`: Used to indicate useful information. The default theme uses the - * brand color for this by default. - * - * - `warning`: Used to indicate warning to the users. Used in custom - * container, badges, etc. - * - * - `danger`: Used to show error, or dangerous message to the users. Used - * in custom container, badges, etc. - * -------------------------------------------------------------------------- */ - -:root { - --vp-c-default-1: var(--vp-c-gray-1); - --vp-c-default-2: var(--vp-c-gray-2); - --vp-c-default-3: var(--vp-c-gray-3); - --vp-c-default-soft: var(--vp-c-gray-soft); - - --vp-c-brand-1: var(--vp-c-indigo-1); - --vp-c-brand-2: var(--vp-c-indigo-2); - --vp-c-brand-3: var(--vp-c-indigo-3); - --vp-c-brand-soft: var(--vp-c-indigo-soft); - - --vp-c-tip-1: var(--vp-c-brand-1); - --vp-c-tip-2: var(--vp-c-brand-2); - --vp-c-tip-3: var(--vp-c-brand-3); - --vp-c-tip-soft: var(--vp-c-brand-soft); - - --vp-c-warning-1: var(--vp-c-yellow-1); - --vp-c-warning-2: var(--vp-c-yellow-2); - --vp-c-warning-3: var(--vp-c-yellow-3); - --vp-c-warning-soft: var(--vp-c-yellow-soft); - - --vp-c-danger-1: var(--vp-c-red-1); - --vp-c-danger-2: var(--vp-c-red-2); - --vp-c-danger-3: var(--vp-c-red-3); - --vp-c-danger-soft: var(--vp-c-red-soft); -} - -/** - * Component: Button - * -------------------------------------------------------------------------- */ - -:root { - --vp-button-brand-border: transparent; - --vp-button-brand-text: var(--vp-c-white); - --vp-button-brand-bg: var(--vp-c-brand-3); - --vp-button-brand-hover-border: transparent; - --vp-button-brand-hover-text: var(--vp-c-white); - --vp-button-brand-hover-bg: var(--vp-c-brand-2); - --vp-button-brand-active-border: transparent; - --vp-button-brand-active-text: var(--vp-c-white); - --vp-button-brand-active-bg: var(--vp-c-brand-1); -} - -/** - * Component: Home - * -------------------------------------------------------------------------- */ - -:root { - --vp-home-hero-name-color: transparent; - --vp-home-hero-name-background: -webkit-linear-gradient( - 120deg, - #bd34fe 30%, - #41d1ff - ); - - --vp-home-hero-image-background-image: linear-gradient( - -45deg, - #bd34fe 50%, - #47caff 50% - ); - --vp-home-hero-image-filter: blur(44px); -} - -@media (min-width: 640px) { - :root { - --vp-home-hero-image-filter: blur(56px); - } -} - -@media (min-width: 960px) { - :root { - --vp-home-hero-image-filter: blur(68px); - } -} - -/** - * Component: Custom Block - * -------------------------------------------------------------------------- */ - -:root { - --vp-custom-block-tip-border: transparent; - --vp-custom-block-tip-text: var(--vp-c-text-1); - --vp-custom-block-tip-bg: var(--vp-c-brand-soft); - --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft); -} - -/** - * Component: Algolia - * -------------------------------------------------------------------------- */ - -.DocSearch { - --docsearch-primary-color: var(--vp-c-brand-1) !important; -} diff --git a/site/guide/advanced/decisions.md b/site/guide/advanced/decisions.md index bddc29e24..07c6a5657 100644 --- a/site/guide/advanced/decisions.md +++ b/site/guide/advanced/decisions.md @@ -12,7 +12,8 @@ This allows changesets to be added and accumulated safely, with the knowledge th ## How dependencies are bumped -> NOTE: This refers specifically to a feature of changesets used in mono-repos +> [!NOTE] +> This refers specifically to a feature of changesets used in mono-repos When changesets are generated, we check to see if the selected packages will leave semver for any other packages within the mono-repo. diff --git a/site/guide/basic/cli.md b/site/guide/basic/cli.md index 00906945b..6dea0943f 100644 --- a/site/guide/basic/cli.md +++ b/site/guide/basic/cli.md @@ -138,7 +138,8 @@ The status command provides information about the changesets that currently exis - `--since` - to only display information about changesets since a specific branch or git tag (such as `main`, or the git hash of latest). While this can be used to add a CI check for changesets, we recommend not doing this. We instead recommend using the [changeset bot](https://github.com/apps/changeset-bot) to detect pull requests missing changesets, as not all pull requests need one if you are on GitHub. -> NOTE: `status` will fail if you are in the middle of running `version` or `publish`. If you want to get changeset status at the time of a version increase and publish, you need to run it immediately before running `version`. +> [!NOTE] +> `status` will fail if you are in the middle of running `version` or `publish`. If you want to get changeset status at the time of a version increase and publish, you need to run it immediately before running `version`. ## pre @@ -148,7 +149,8 @@ changeset pre [exit|enter {tag}] The pre command enters and exits pre mode. The command does not do any actual versioning, when doing a pre-release, you should run changeset pre enter next(or a different tag, the tag is what is in versions and is the npm dist tag) and then do the normal release process with changeset version and changeset publish. For more information about the pre command, see the prereleases [the prereleases documentation](https://github.com/changesets/changesets/blob/master/docs/prereleases.md). -> NOTE: pre-releases are a very complicated feature. Many of the safety rails that changesets helps you with will be taken off. We recommend that you read both [problems publishing in monorepos](../advanced/publishing-in-monorepos.md) and be clear on both exiting and entering pre-releases before using it. You may also prefer using [snapshot releases](../advanced/snapshot-releases.md) for a slightly less involved process. +> [!NOTE] +> Pre-releases are a very complicated feature. Many of the safety rails that changesets helps you with will be taken off. We recommend that you read both [problems publishing in monorepos](../advanced/publishing-in-monorepos.md) and be clear on both exiting and entering pre-releases before using it. You may also prefer using [snapshot releases](../advanced/snapshot-releases.md) for a slightly less involved process. ## tag diff --git a/site/guide/introduction/getting-started.md b/site/guide/introduction/getting-started.md index 3ab84a5bb..3aa89db68 100644 --- a/site/guide/introduction/getting-started.md +++ b/site/guide/introduction/getting-started.md @@ -50,7 +50,8 @@ $ yarn changeset ::: -> Note: You can run `changeset add` to add a changeset if you want to, but running Changesets without any command works as well. +> [!NOTE] +> You can run `changeset add` to add a changeset if you want to, but running Changesets without any command works as well. ## Versioning and publishing diff --git a/site/package.json b/site/package.json index dc47944ea..2d4c454cc 100644 --- a/site/package.json +++ b/site/package.json @@ -11,6 +11,7 @@ }, "devDependencies": { "oxc-minify": "^0.128.0", - "vitepress": "^2.0.0-alpha.17" + "vitepress": "^2.0.0-alpha.17", + "vitepress-plugin-group-icons": "^1.7.5" } } From a7ba9c7bc9f4d69aea2c3a891fc5f1bd3296e1cd Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 6 May 2026 14:36:20 +0800 Subject: [PATCH 08/80] Add head tags --- site/.vitepress/config.ts | 22 +++++++++++++++++++--- site/.vitepress/theme/custom.css | 2 +- site/public/og-image.png | Bin 0 -> 11004 bytes 3 files changed, 20 insertions(+), 4 deletions(-) create mode 100644 site/public/og-image.png diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts index ee15e7f4f..fa40cbf83 100644 --- a/site/.vitepress/config.ts +++ b/site/.vitepress/config.ts @@ -6,10 +6,26 @@ import { import packageJson from "../../packages/cli/package.json" with { type: "json" }; const changesetsVersion = packageJson.version; +const ogTitle = "Changesets"; +const ogDescription = + "A tool to manage versioning and changelogs with a focus on multi-package repositories"; +const ogUrl = "https://changesets.dev"; +const ogImage = "https://changesets.dev/og-image.png"; export default defineConfig({ - title: "Changesets", - head: [["link", { rel: "icon", href: "logo.svg" }]], + title: ogTitle, + description: ogDescription, + head: [ + ["link", { rel: "icon", href: "logo-light.svg" }], + ["meta", { property: "og:type", content: "website" }], + ["meta", { property: "og:title", content: ogTitle }], + ["meta", { property: "og:image", content: ogImage }], + ["meta", { property: "og:url", content: ogUrl }], + ["meta", { property: "og:description", content: ogDescription }], + ["meta", { property: "og:site_name", content: ogTitle }], + ["meta", { name: "twitter:card", content: "summary_large_image" }], + ["meta", { name: "theme-color", content: "#006dcc" }], + ], lastUpdated: true, cleanUrls: true, markdown: { @@ -43,7 +59,7 @@ export default defineConfig({ nav: [ { text: "Guide", - link: "/introduction/getting-started", + link: "/guide/introduction/getting-started", }, { text: `v${changesetsVersion}`, diff --git a/site/.vitepress/theme/custom.css b/site/.vitepress/theme/custom.css index 7a7bf537a..6dc2542bc 100644 --- a/site/.vitepress/theme/custom.css +++ b/site/.vitepress/theme/custom.css @@ -42,7 +42,7 @@ } /* Blur effect for navigation bars */ -.VPNavBar, +.VPNavBar:not(.home.top), .VPLocalNav { backdrop-filter: saturate(180%) blur(20px); } diff --git a/site/public/og-image.png b/site/public/og-image.png new file mode 100644 index 0000000000000000000000000000000000000000..5e1a15bbb8c6da051b8e83d269ffd75883d6af2b GIT binary patch literal 11004 zcmdtIWl)?!^Dp}BE-bpZ6JUX0!QEkz;6Wm|1qeE{FH6^YPxQTmO4Lo%!-i)%5e5?ym0Xo~d7iuC^)+pAH`Y0GPU(@>2l7zMq0o zxRCqL2`^g`0DyFLwVpq|ySt-$r10?bKX~?E&VscEnJa*#lSs+7MENctWC4iT0pULZ z5o?;XC7Fsnz^Dk2b_Gn!00C3rNdlmsNBL zc$ER0R)v}aqpqv|q4Dsc+o~ zZNR?k_51K!45qNGPDI5x=2Je8+_UesZHz){rcQn-*~PXVfzPboW)*&~ZSD++N|n{N zdf9(Fx3IFgy*Dwtpk?}cab+!J^s2r4XTj`Q*T9Hj{r2+F4gbrS(XETNzZW0NyF9uM zgu;I3qUXKy`(gG)>J=N}!97;t#g9F62;(P=Q-5*3ts(X4lKvZc003Ne>dFeweP(w$ z0`C0{pmJ}Esf)q?nf}j)<=GPAzkl}K)sjAc@jo6RvJxc!#W_N{VEvC#Uc7ioOoa6x z9Mp{ky~6(woarD4=s!5{yD1gj|2Yn&*X}x3ghce;i)s$Z4iR@FO?9YJ7{%WfpI7|D(hI`|#N7wLkx`Tjye8 z`>YUI<|y*S%vD(h07zw981s(Q-dS2(=a1F#24P@j#o}8!*Ix5T*)Zua|5E@Aq)MPD z_lt^l_AM-mWRGzjZS&j4Pm{^}pqCyI2{b8B-)gmRm%hej-R^Fx=FlW6Dq2&N!g`DW0ov@8K7c z$lp_oZKdr!Cl28*=MEgei+K;wlSZpx}v4{D-!!r!Utx1X5$of$b-YN%18iw zL!5qdljU>!5A%*{_wbfGMPrVy->yPov|QfQnM)}%E5{KRjyRHayJI&;%64aWcUNLN zCpX!|p{4Mer5B&7NcnmM0pN#OX2rOr?L^9v8mSSE0fh5N&Rvzt--=kqD$5ag{Ru}$%aFFBnVVjmCd9@-R!YR zVXh;0N+J(@5%tCL&T9630PsWW&xf<-ha?4Z4Yx^#NV5{iaP|zvxLV_=))uYl_r&Ny z(p%}0){@=0CXhENBDK)0d!H@fp_7u^y)z|Cmw?1A_2!3DmRU9ra=4gl#a-j#`U=g> zKFI0*ICCXI_+Wvwh{|~CG42@CZl|L${9?If;sEJK5fa5*3hUkhe~-32F34{3m{Ch% z0DE}rGMOQ=5t;pOadnDrRp*MfGzs_Ai4$o+;Z;N3M7{|BuUMa+k?k$))b-sAi!EP4 z>IP{;enNQb(%4yIXfuAw5d{c~2}?lT`S0Iv}uOL-m(8XrVX z_t?K!MqgSH2w+C3=cTYsSqxXLQ_G{MO}W_52r-=tStpNRk3kRQRiBtv2)vFSv$nR< z5}AFhX`;!sno{>Rkc^#lU4o5h5ouSb$ZtIB@lT56s#>$GUc3d#mwA4~NDmJzTaIlw zsbk*L*a9YLJb}3WxssJH?P>J%R5s@3L#vnMXJQwWxW9WDJc71wtH#S9hI8K_KF@df z!A0#xcVc*cFFR+e2kG>&(_6Opps^ zRC7n_>MYAe5auYtd{~xh&kc?1H_3`2h!Ldc0xtpx4))5dI<0hG+s=LH|fQS3? zYoGh)Su$@ncKfHn*X!KnWBZ9!cq(-99g)=uzTB_;k@$&nh~eP9$%?Mn z+DH%Y{e|1NzJJ}XRG0pv85zsq?JwliH;AE03B)H^E-C}FV0q>J{f$FX`-%8fmkw8F5}QaK*hWuZ`Y6PHaA00FlscH;g5m0E#EbcV-2(%;vhVrr ze(3Ocd&fAI_DS7@sy8$%BliZp`i1P9Zu^uzerMB!xZlukF7t8d>Py{-`BFh2RkcXe zI8P66P|`4$OmM$wG&R!)?|-8Hd7dTxZjG9B%%Tpt_+2IccS{zjB^XEuJWJC!Irw`XamNUu7?#; z!w>NDTFfbpf#!9xz2*A%h^gJLhANRZ*?>y?cCFt$M;&TNYrJ)EkZE$AaOq*98-K4T zYB4{y(0qnd}MBA+%v(aaY4aj#g&?RVP3*!aFupeU8Uf&;@*Zjha~5vw-C;U#X1> zEhifpVBM?D?Td5sr@IuD_oc(zJP_e;0}JSVK-*?UizX>47J8n@P;m6I3wU2)+pLC| z`BJB`p}_?3!~%Q_4>w2N*Sg0KBm{I3ITY(%BLz{DG{r4qnN>5sq+^RG1AZ=k=U>w( zb^An8*Kc~|`%^)25kE({!S>2(%lw}+cQyJt3bA#oBqzi9p5yh48z(~Sxz!3!am${@ z2T_0nXyFr$n0l~8a=cPrC!X&mW@OX#W4o61?lTWw{w3xy%OC4VEA2No0}y*hwZESX z4CCU58@2J^>40Ty!dK#deJ-156dgiXMamUQ8I5~c$FdwX7WoEG`1uz75<8a`|25J z_1c}llAl%O1A_+euN3(_Tm8Z^ML8eaZ3WKc`gFD(xU9_`S5uVp_&bbK5pn~j*G|Rk zRcyMh8E-kU9)C@f^r5@yf_B*0a3Oh6ysLsJ*&Tr3>oKREskmeu!@zAMM4}3!Cun#S zf}%i27??`(60M~VAQQFS_HP3Xk1Gsu*`Q=p@tN-)4EM@?7D2M0n5m9>-rU?uvhgIN z)qQ=Bb2nYLW~ERuOmd>aINCu>ZQx~S-_~6*aF)RQE2*s|HGM2ZMs1A@Ga$T?kIkDo zQ}HU+*inI*dIGe=-8U+gAsRcMD|6bcrg$EdNmbyVdDoZIsD+PF zbUwZr31K2E+ijz-DtQ@twQZ&Uv;$vJGfcEuTEc+)i#mBBTCz%{Fd0ui0cn;@5nR>i zugx7@i6+yY6+as)t9PKmN1y5Q<)Pw9)KI`7RA=?GNOj`ExQJ%bmsfgYAIl3XBBE#l z@9tC{L$$TX9!Ph6ojYpv+J4G${XTZMQueyzmc!`w-ysvVW$h1GYCD}N`h>|gxse6b zV=zH<9b-ebKoHCt^AXClmb~XbNz7>zPT)poFvy7&^=Z4@CvUG1%Q}e2FsV=-Z)Cb6 zVGTlUbo|+;vT0ctQPD`@{Bx=jH}jLgBo{*7F-Yh4Tt$ukvnEKR9<`7mcjO|2_vXaIO50eez{a|evHp*2G*Z|<^+4`K zqaP$nqe4-w$=Tv6a2E>|6ejd{uMPPa6>K`)t>s$(8%IXEJwZX`VSNS{(Mt$5e(~q0 zD9Ebzf!wAL9(24-O&|FglSil4m822EEnpz(a~Z(NoMu@=Ng(hw!Yl5Sq!!L#;<8bP zFhuS3k?lB_6F?2j!)rY9!8@H!J1&*F)J-zC)o)Q#Eun4}Q446s0$krHUpu#vI12m` zpx&A8b&SRGt40_1Zb7;Aa*WFSwb5lVW@aCnFC(T^pZ9H!q zV<$?(3>RO3CdozX?Gjk&E94+1L7XKQ@ zbAvA|Soyrd#ZAk6bEp0S$$Iyv1oO`~gkC^Z^x{NT@A1*0?IY}sbQ|f9apEGWLOPr~ z(kI(q6vpxsdD5v0D`QQ+ zQd17lsEwFl&IP>zrKkPjjaQm)C!p(ntXL5m(>wZPNrZhYP*$G}{iY|A*W7+9iR_0q zqvi`_BWCisWJ>shiKX>kDm^tt>2gJolyGq)qg2<*$HsXv;&BQR%c;aikG2T2JdYB@ zGgrViVxyywgAvrO+7K6k$PuHH$PkG2fnRz}xdtk~RE_+WLXPXQ44q;mx(THiN`q2aorTG{d9I4x!?!PEUKe= zWKVM8&eKGWbO|hJ=<;I@0 z51TTVtC=%ovWm4yyb6S-pv)yFBV2=DzJkx`TvL(5JAbfUqB#y@i4@XCB$+ zK1X?M{^{Hb$CnBG%M9L87vC@zBeQU@EC;dm5z#h}GQI!U5L}E8`Vl4_-$rfVYllF+ zara`pTb@`{3z%XukkmQLduUig=XZQE4KFrT13^Rmo_WdozPMJtx~mJotVPVw;NV|Vu+^=|1Pkbk!BV$YlwN69!m$>s#<3tLK}YS!ehl*nON*YPPIS8 z>Vt(p4gaFU5=Z`8y+-*8!&wAW(V^J40<=ezX)>^3vKAFWBu>?>l!IJ8&45!&2ASTMIpWp5__XYk{G_ zr`p5~z@bB)*P0*0wKqseR>z|} zjp1rGWaxCN0!23bjX~3&G}!!*d=a1B*=a_iw?M= zsV#_z!0Z#w;Ad9?QcKzGoNrMgKl=$rehSBSxd}g$BzB$PTk`Wud*G9&jPg7vVbge- zq~pX^o~?3dAq4horPgaa^nBM;_h%@xx#}7CBs8N)M%YKlF_)x^M~T1hr=~wsT0MwebXKHKVog3>qvFIv$0t$>k z(@VoUvdEV7gm`DwL4oJV>98bf%hWNx+Z`%PdYX!7)7dNeewUlN5kNl$O+_?_pva?Y zWg;&4E*Frb+(X-G8sV7Rg4mx`Pio_nybZQ#@p_H|7T0zLQ*Dqb(eeI@DNH;tB?r|Q zV42-)&(dx!n-9CEA73BYc=x(B`W&>k?*R&QJb3EZx<5f`x%&gJBF(Q105Sf1kf3sw z2<`j~G}}>B=EOVwi+%uO1J@97qG^-gx#?-O$%aJ9moHxDw~NM+fw7?TQQQYTn>Z{Q zTxbfqzv(mdG0-semOCB<6D-sXL{)837LrV()f8Z!Bb*4K=Bw{}0nO$jg*!Mc`YGy= zRbZGOsfuOKI%a$Xe(OLw{`-l#WUTyGS|LFy-rzPCP$J(G)pKZ+5dBcU6*d*J;EEVu zfEH^n9Gpa-XATEd)n}`4{ow+!zon#rqoKT5Op@D>JcjXW;pO5M#f@Sz`0<8Upv6ws zT+)g%Mc6P`?ORR%O2^u_6C9@#G6=;-!3a{tK5Vr}fJHjCxv-?<1?JAxHrhIjy?|e< zSNEWGPy5lQe)08_?_*^;uM2Yp=HxZ5q|NS9urJo7VV~Vx>Lu=)YF?}~^-LR(#7sMyqC5A7M|Jc@(#tPq}oZl1BYYR01pg>yMKK2-)2E8z)6r||Y;5(JIjuxN&R?~nTv4*93 zUtNeVBk~%%L8Gz^JTKP>*hONg^}U77(DajN=UM~;pq*gV(|`|y%8ovdd2bE2+wCN6 z=q!gKSSs8f9;n(!a($esH%G+=h=U>tDng^35HIMbsd*85^Ui*A_?uXhOydK?Ja?oZ z%q62BoEygH;}QU#-uIZpo))YiLkjQlu@C-fd&cgdkLrw~fTKh+Sm~|ZXTUO&9$ROv z0@QOk4WswY%M@2eVHaT8)OC1|;7aq5*P5b~nBqp(#m6#@R#)taF6i5=F2n?<9TWo|`M z|9#$imFCg-lIq$puH6pC;#BpO3f^HJYc%D+v)seneo)ljh0O6gNeyU$Lszwf+HYv- z&@%J6wST}`8!N6Yj$@7j>>u%R5GZNKstT+5Qb5!sI%US$N9kVIy zd+_LDppH9c7iF1I1oY1bH9sTTQ z!_%5Nf`b6(w4X5qk_%K{$l7_3*7w<8X5ol&8}Zg{0}~iUC*~4Cm(~f+7OaCCH>udDD<3fjGW7 zUSYd3QZk3KIS+Xg$Qhpi6*q_M^V&t~=tA`h4-lCbvA(3A?wqW*n#HOT#TdI`!@p8W{$A7RL zlJiviZei>F4*l}xy4TUoF>;)d!t^8Hah731Zu*NqZ`4TQFJ?Z-G%%TYaQdFT1 zU}zA$%Dm92xZ(Cm@KsjTa(vBf}Fj}J&~Le4a3JG5{k zQTE^?{;zR-fli@6UifaPS9!5F z4mtKfLB~M;lI+JBwekW=E~+KELFHYFC9=U28!SWLBpCgW?QdQ|Y(Akz@l2$jASwZG zGTwulm!Q#!_z!IWv;P*EK(Z0U&-7R+Z5FRfsUP|ZK9=TP%+%!gAw~P%scXPHJVQ5a zx*G`R!?B8BvE+9NEdRh1^)oKEE*X4E+R5Hr0u!G-B zx7XMTypc(luE&d}jBLXZb~Z(wxct@+?Clinlub=X_bWzCD^VM>>+Q{{x-^;UF85#< zQw!WJI-_;-rkLgx<5kT`?;?uYLojWZbq(9zOw<@@ZkT>LR+u4st+FhN;U8E;v}5uY z9)=jir{~-sTGm0fq_0#gINKIVW8xOevof4|Nw{i-*V~6>8 za{H;1=NaUux&h(m1K#VJ667rV3ow)+pqF7*(Z#_M!V%#k)!O7wc+)rc14(wDev88N z_@&4pwEwgPO5jDzAt;FWY-iisQU#&C z6?R|(@6Lu(X_>Aif!q@7fO@J*elNDWZ@v%KqD=&MTVT%evh_EE%vtETMWhbJePST} zaklyhjj23SnHfoxAmB_ml5R;`RK{vF9N^9Q7U~tjC$KCcgL(E*m0aH6EM5CzVy8<&o zz@tv0L%@1G7!V$Cz~F0FE?8nG7=uRd0&d@%2r>%Vp7-z6z439o&4@lMwT^o6L`b^x zGc)IAYn+;Ty0B|!Hd``;d`)b;intcR+0r7Xgi)Dj>>746^NW$W^ zr7}pDh#XcZA1ssH>TP_(>XR9+fv8SLgtmZ#@fb?Jp}X6ln*KyvBIsALZE7&H@R~K3%N+!aEP|Sr7S&Nk`Qh- zU&v0vP{|A~#W&x_-m9^tsoX?9#@|tsuitS@yg`YiL!RJO1W{sTD2QzDUsXRQyE0Ur zO$K<0;{;di#cRymc2BG3I-f<)RFZdSUa{THWjS=effa2LK9f<*P>scA+c8@a)QOLO zXV_so%T5xmzdm?@qa9bbl;(yZW*)SRy$r zFtSyU^qib^j5I$CGYU?Lt^`{PYk&D&Q!*@DiZD^M1_y((m2x#uJCf5_ux;9EcE;a6 z$A@s*jl-5%Oh?<*;e}yD4pSNZ<1rg8M)CcJmni`$_6`?rk$)@fo?9qDd7$(4!iCh; zA6vBLgSP)o&~EOx<7fU5l&1hE>jY6EiNLneKeTccK*n773hLJ5$-v8qzzPB$-`EwB zyWgd-i!2Cl^bb64|4OR~}&(0Ib zg;Rcp&7jr`JI-?{#1%*bJ$TY0JnEKE!*tkUBK{5Y+pC24U zv2n>`bbz&RHiY7$D(Tyj1%1KD-}E2??{A-h4zR=i1Zlf*ComxxP|3p-uhw9TLFyATmhM4%{wU13!p z*1elf0k`q6S>jLATp8PuS!G$8h4wMp_o)wq)orHK<D+ZrrJ|fPuOYDFk{-XQu z$f6~dpR;F-CV}P>hbAG>?PDt3s*_4^8}SEK2p{(QBqwu7#S(Y_*{6#*m;Wg1Zy)%g z^d)TJ2iX3;*?koQ4mvy=5A_Z$HbjYd{c;lD2XJxYEr;G4Mv4DI<>-C-N69B0$)Q^eV)17{eP3N_Dtl~rQ3(Tkj*`P)V?QUf?hy{R=G z?JK{eax5{uM_x5BX?o^g1Vwj#+s>+4%>5fkV=FJFE&Zyk5AneJJ3Ys)xLLr%&h(Yh zI1aB{$=x1N^95z42GCxK$IW^f>X%tI_Fz$myyCM`s?R!ut_y$C&_SEYwC=`JT-FM_ z`W8CHDJws^KVo!-KWfe#Ee?GD0<}|h=(^<@4%ev9%c=+NX6sUs+}}Ok{p-hBCSE@KG%|?7;m#qx zKfv3A+569uHW6`u4Vm6@G`q~{t5s(jCFhva#3k7`I?m0c410_+L`OAG_ixorW#BV- zwMHj~{q1>A_Df1EGi;ZKTK$bQQ*8b4lAp7k*prhtnM_s9hUL6I_@zTOQZ#qI*-3u} z$YhH!dDp|Po^P^P8xEQFit_$3G1s7oh40vv#b6)mTfbk%w9hmn7iv1-v479s7C-Xb z7!@M%bh3l?c7TKO=rX!2agq<}X>bWN7Vpf98MI8nA2JKXhR%;!v@w@^je~jpWKtBp zoSNt7{5ns=7qRVjq2IAyk+IjsfF+xT>5%e2m3yULhuC`stp^G@unkRtCExeaAcLfT zlW%q}O{?g#d)7uF5BnyBp50zgdMMA`czk(%ps&jk<5b&830EB|;yLv8<2F)GYwCEb zpz)7g5C^upA=J5UQTSI)<=8Ql<^kS7z79D}_sb1$M$eiT z&RE!2_sqpHP}X>H8VOO#cC8(W>UgHmQM z13Eg%eRk)kWZvVLAO#i1@c{p*ae^h<(Z7q0^SjkxKyt4sn`_q;e~IlNQ1~o5!Ssc# z*QbAM7g7F^Oa5*vE3}2jsqG1E5ErU@vMtuzgK<(XjuyP?nDzw&YmI0LwQqVt9+Vc$ zSCge#^ZMHU>4GQ~++xuBuzn?s{GIG?KRsEhphbenLB?-}yYr(BZw|l2y~!tOW4gMz z-tY}&`~J&VhkBo=dr4T~rBT59uGTlB<~qXIeKVh0Prt7~ZC$-M?sRIhU)R}9vR>9?>V zRbz;7QAysupU*a8e;u3CoI!8jKiM542PEG0gp5v+0h|F|2AfwMvBJPV0oq5h>^O~} zM^Y1txkR)Op{~w5c?KA&}m~a1=5(8)dw|f*Y kldL?t|K$k&Kk@T8$Pad?J`hIA|7TJCv9@x#qGjO!0&~?D7XSbN literal 0 HcmV?d00001 From b84d60898d27e990ee55f8c9bf68c378dd8e627a Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 6 May 2026 17:55:53 +0800 Subject: [PATCH 09/80] Fix lint error --- eslint.config.mjs | 1 + 1 file changed, 1 insertion(+) diff --git a/eslint.config.mjs b/eslint.config.mjs index fd05019f3..426baba85 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -90,6 +90,7 @@ export default defineConfig( { files: [ "**/index.ts", // to be removed in next release (v4) when we are dropping default export + "**/.vitepress/config.ts", "**/vitest.config.mts", "**/eslint.config.mjs", ], From 13f43a8a69a31bdd8dd05a511861e414428ba134 Mon Sep 17 00:00:00 2001 From: Bjorn Lu Date: Wed, 6 May 2026 23:56:57 +0800 Subject: [PATCH 10/80] Apply suggestions from code review Co-authored-by: Adam Haglund --- site/.vitepress/theme/custom.css | 5 +++++ site/index.md | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/site/.vitepress/theme/custom.css b/site/.vitepress/theme/custom.css index 6dc2542bc..de3fe4e10 100644 --- a/site/.vitepress/theme/custom.css +++ b/site/.vitepress/theme/custom.css @@ -46,3 +46,8 @@ .VPLocalNav { backdrop-filter: saturate(180%) blur(20px); } + +.VPFeature .details > a { + color: var(--vp-c-text-1); + text-decoration: underline; +} diff --git a/site/index.md b/site/index.md index c2a5ac08f..e3d5fbace 100644 --- a/site/index.md +++ b/site/index.md @@ -23,7 +23,7 @@ features: details: Automatically updates versions based on change types. - icon: 📦 title: Monorepo Support - details: Simplifies managing multiple packages within one repository. + details: Supports pnpm, yarn, and npm workspaces. - icon: 📖 title: Changelog Generation details: Automatically creates package changelogs. From c3941ac1f87e820d0b5334d2648eaad6a1c43421 Mon Sep 17 00:00:00 2001 From: bluwy Date: Thu, 7 May 2026 10:20:15 +0800 Subject: [PATCH 11/80] Simplify main readme --- README.md | 93 +-------------------------------------- site/.vitepress/config.ts | 9 ++++ site/acknowledgements.md | 50 +++++++++++++++++++++ 3 files changed, 60 insertions(+), 92 deletions(-) create mode 100644 site/acknowledgements.md diff --git a/README.md b/README.md index ed645f2b2..821408ec4 100644 --- a/README.md +++ b/README.md @@ -18,95 +18,4 @@ The `changesets` workflow is designed to help when people are making changes, al Changesets has a focus on solving these problems for multi-package repositories, and keeps packages that rely on each other within the multi-package repository up-to-date, as well as making it easy to make changes to groups of packages. -## How do we do that? - -A `changeset` is an intent to release a set of packages at particular [semver bump types](https://semver.org/) with a summary of the changes made. - -The **@changesets/cli** package allows you to write `changeset` files as you make changes, then combine any number of changesets into a release, that flattens the bump-types into a single release per package, handles internal dependencies in a multi-package-repository, and updates changelogs, as well as release all updated packages from a mono-repository with one command. - -## How do I get started? - -If you just want to jump in to using changesets, the [Intro to using changesets](./docs/intro-to-using-changesets.md) and [@changesets/cli](./packages/cli/README.md) docs are where you should head. - -If you want a detailed explanation of the concepts behind changesets, or to understand how you would build on top -of changesets, check out our [detailed-explanation](./docs/detailed-explanation.md). - -We also have a [dictionary](./docs/dictionary.md). - -## Integrating with CI - -While changesets can be an entirely manual process, we recommend integrating it with how your CI works. - -To check that PRs contain a changeset, we recommend using [the changeset bot](https://github.com/apps/changeset-bot), or if you want to fail builds on a changesets failure, run `yarn changeset status` in CI. - -To make releasing easier, you can use [this changesets github action](https://github.com/changesets/action) to automate creating versioning pull requests, and optionally publishing packages. - -## Documentation - -- [Intro to using changesets](./docs/intro-to-using-changesets.md) -- [Detailed explanation](./docs/detailed-explanation.md) -- [Common questions](./docs/common-questions.md) -- [Adding a changeset](./docs/adding-a-changeset.md) -- [Automating changesets](./docs/automating-changesets.md) -- [Checking for changesets](./docs/checking-for-changesets.md) -- [Command line options](./docs/command-line-options.md) -- [Config file options](./docs/config-file-options.md) -- [Decisions](./docs/decisions.md) -- [Dictionary](./docs/dictionary.md) -- [Fixed packages](./docs/fixed-packages.md) -- [Linked packages](./docs/linked-packages.md) -- [Modifying changelog format](./docs/modifying-changelog-format.md) -- [Prereleases](./docs/prereleases.md) -- [Problems publishing in monorepos](./docs/problems-publishing-in-monorepos.md) -- [Snapshot releases](./docs/snapshot-releases.md) -- [Versioning applications and other non-npm packages](./docs/versioning-apps.md) -- [Experimental Options](./docs/experimental-options.md) - -## Cool Projects already using Changesets for versioning and changelogs - -- [atlaskit](https://atlaskit.atlassian.com) -- [emotion](https://emotion.sh/docs/introduction) -- [keystone](https://keystonejs.com) -- [react-select](https://react-select.com/home) -- [XState](https://xstate.js.org) -- [pnpm](https://pnpm.io) -- [tinyhttp](https://github.com/talentlessguy/tinyhttp) -- [Firebase Javascript SDK](https://github.com/firebase/firebase-js-sdk) -- [Formik](https://github.com/jaredpalmer/formik) -- [MobX](https://github.com/mobxjs/mobx) -- [Nhost](https://github.com/nhost/nhost) -- [verdaccio](https://verdaccio.org) -- [Chakra UI](https://chakra-ui.com) -- [Astro](https://astro.build) -- [Biome](https://biomejs.dev) -- [SvelteKit](https://kit.svelte.dev) -- [Hydrogen](https://hydrogen.shopify.dev) -- [react-pdf](https://github.com/diegomura/react-pdf) -- [GraphQL Code Generator](https://github.com/dotansimha/graphql-code-generator) -- [GraphQL Yoga](https://github.com/dotansimha/graphql-yoga) -- [GraphQL-Mesh](https://github.com/Urigo/graphql-mesh) -- [GraphiQL](https://github.com/graphql/graphiql) -- [wagmi](https://github.com/wagmi-dev/wagmi) -- [refine](https://github.com/pankod/refine) -- [Modern Web](https://modern-web.dev) -- [Atomizer](https://github.com/acss-io/atomizer) -- [Medusa](https://github.com/medusajs/medusa) -- [OpenZeppelin Contracts](https://github.com/OpenZeppelin/openzeppelin-contracts) -- [Block Protocol](https://github.com/blockprotocol/blockprotocol) -- [Remix](https://remix.run/) -- [Clerk](https://github.com/clerk/javascript) -- [Hey API](https://github.com/hey-api/openapi-ts) -- [neverthrow](https://github.com/supermacro/neverthrow) -- [Apollo Client](https://github.com/apollographql/apollo-client) -- [Adobe Spectrum CSS](https://github.com/adobe/spectrum-css) -- [Adobe Spectrum Web Components](https://github.com/adobe/spectrum-web-components) -- [React Email](https://react.email) - - - -# Thanks/Inspiration - -- [bolt](https://github.com/boltpkg/bolt) - Brought us a strong concept of how packages in a mono-repo should be able to interconnect, and provided the initial infrastructure to get inter-package information. -- [Atlassian](https://www.atlassian.com/) - The original idea/sponsor of the changesets code, and where many of the ideas and processes were fermented. It was originally implemented by the team behind [atlaskit](https://atlaskit.atlassian.com). -- [lerna-semantic-release](https://github.com/atlassian/lerna-semantic-release) - put down many of the initial patterns around updating packages within a multi-package-repository, and started us thinking about how to manage dependent packages. -- [Thinkmill](https://www.thinkmill.com.au) - For sponsoring the focused open sourcing of this project, and the version two rearchitecture. +Visit https://changesets.dev to learn more. diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts index fa40cbf83..f5ab0a014 100644 --- a/site/.vitepress/config.ts +++ b/site/.vitepress/config.ts @@ -61,6 +61,15 @@ export default defineConfig({ text: "Guide", link: "/guide/introduction/getting-started", }, + { + text: "Resources", + items: [ + { + text: "Acknowledgements", + link: "/acknowledgements", + }, + ], + }, { text: `v${changesetsVersion}`, items: [ diff --git a/site/acknowledgements.md b/site/acknowledgements.md new file mode 100644 index 000000000..fb839e95c --- /dev/null +++ b/site/acknowledgements.md @@ -0,0 +1,50 @@ +# Acknowledgements + +## Inspirations + +- [bolt](https://github.com/boltpkg/bolt) - Brought us a strong concept of how packages in a mono-repo should be able to interconnect, and provided the initial infrastructure to get inter-package information. +- [Atlassian](https://www.atlassian.com/) - The original idea/sponsor of the changesets code, and where many of the ideas and processes were fermented. It was originally implemented by the team behind [atlaskit](https://atlaskit.atlassian.com). +- [lerna-semantic-release](https://github.com/atlassian/lerna-semantic-release) - put down many of the initial patterns around updating packages within a multi-package-repository, and started us thinking about how to manage dependent packages. +- [Thinkmill](https://www.thinkmill.com.au) - For sponsoring the focused open sourcing of this project, and the version two rearchitecture. + +## Cool Projects using Changesets + +- [atlaskit](https://atlaskit.atlassian.com) +- [emotion](https://emotion.sh/docs/introduction) +- [keystone](https://keystonejs.com) +- [react-select](https://react-select.com/home) +- [XState](https://xstate.js.org) +- [pnpm](https://pnpm.io) +- [tinyhttp](https://github.com/talentlessguy/tinyhttp) +- [Firebase Javascript SDK](https://github.com/firebase/firebase-js-sdk) +- [Formik](https://github.com/jaredpalmer/formik) +- [MobX](https://github.com/mobxjs/mobx) +- [Nhost](https://github.com/nhost/nhost) +- [verdaccio](https://verdaccio.org) +- [Chakra UI](https://chakra-ui.com) +- [Astro](https://astro.build) +- [Biome](https://biomejs.dev) +- [SvelteKit](https://kit.svelte.dev) +- [Hydrogen](https://hydrogen.shopify.dev) +- [react-pdf](https://github.com/diegomura/react-pdf) +- [GraphQL Code Generator](https://github.com/dotansimha/graphql-code-generator) +- [GraphQL Yoga](https://github.com/dotansimha/graphql-yoga) +- [GraphQL-Mesh](https://github.com/Urigo/graphql-mesh) +- [GraphiQL](https://github.com/graphql/graphiql) +- [wagmi](https://github.com/wagmi-dev/wagmi) +- [refine](https://github.com/pankod/refine) +- [Modern Web](https://modern-web.dev) +- [Atomizer](https://github.com/acss-io/atomizer) +- [Medusa](https://github.com/medusajs/medusa) +- [OpenZeppelin Contracts](https://github.com/OpenZeppelin/openzeppelin-contracts) +- [Block Protocol](https://github.com/blockprotocol/blockprotocol) +- [Remix](https://remix.run/) +- [Clerk](https://github.com/clerk/javascript) +- [Hey API](https://github.com/hey-api/openapi-ts) +- [neverthrow](https://github.com/supermacro/neverthrow) +- [Apollo Client](https://github.com/apollographql/apollo-client) +- [Adobe Spectrum CSS](https://github.com/adobe/spectrum-css) +- [Adobe Spectrum Web Components](https://github.com/adobe/spectrum-web-components) +- [React Email](https://react.email) + + From 1eeb2252e09599b658d124345cbe7a3ec97d65b9 Mon Sep 17 00:00:00 2001 From: bluwy Date: Thu, 7 May 2026 10:43:21 +0800 Subject: [PATCH 12/80] Add Netlify stuff --- netlify.toml | 6 ++++++ site/.vitepress/config.ts | 20 ++++++++++++++++++-- site/index.md | 2 +- 3 files changed, 25 insertions(+), 3 deletions(-) create mode 100644 netlify.toml diff --git a/netlify.toml b/netlify.toml new file mode 100644 index 000000000..3bc4556e9 --- /dev/null +++ b/netlify.toml @@ -0,0 +1,6 @@ +[build] +publish = "site/.vitepress/dist" +command = "pnpm site:build" + +[build.environment] +NODE_VERSION = "24" diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts index f5ab0a014..5a5d1b232 100644 --- a/site/.vitepress/config.ts +++ b/site/.vitepress/config.ts @@ -5,7 +5,16 @@ import { } from "vitepress-plugin-group-icons"; import packageJson from "../../packages/cli/package.json" with { type: "json" }; +// Netlify envs +const commitRef = process.env.COMMIT_REF; + const changesetsVersion = packageJson.version; +const currentYear = new Date().getFullYear(); +const netlifyLink = `Netlify`; +const commitLink = commitRef + ? `${commitRef.slice(0, 7)}` + : "dev"; + const ogTitle = "Changesets"; const ogDescription = "A tool to manage versioning and changelogs with a focus on multi-package repositories"; @@ -45,17 +54,20 @@ export default defineConfig({ editLink: { pattern: "https://github.com/changesets/changesets/edit/main/site/:path", }, - socialLinks: [ { icon: "discord", link: "https://chat.changesets.dev" }, { icon: "github", link: "https://github.com/changesets/changesets" }, { icon: "npm", link: "https://npmx.dev/package/@changesets/cli" }, ], - search: { provider: "local", }, + footer: { + message: `This site is powered by ${netlifyLink}`, + copyright: `© ${currentYear} Changesets (${commitLink})`, + }, + nav: [ { text: "Guide", @@ -68,6 +80,10 @@ export default defineConfig({ text: "Acknowledgements", link: "/acknowledgements", }, + { + text: "Code of Conduct", + link: "https://github.com/changesets/.github/blob/main/CODE_OF_CONDUCT.md", + }, ], }, { diff --git a/site/index.md b/site/index.md index e3d5fbace..ff1c41e96 100644 --- a/site/index.md +++ b/site/index.md @@ -38,6 +38,6 @@ import { VPHomeSponsors } from 'vitepress/theme' From 377d072a3a5f92d923eabc824f1f1c2ff98393cd Mon Sep 17 00:00:00 2001 From: bluwy Date: Tue, 12 May 2026 23:12:23 +0800 Subject: [PATCH 13/80] Update picomatch links --- site/guide/advanced/fixed-packages.md | 2 +- site/guide/advanced/linked-packages.md | 2 +- site/guide/basic/configuration.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/site/guide/advanced/fixed-packages.md b/site/guide/advanced/fixed-packages.md index 5ff54a3e9..ba4832b2a 100644 --- a/site/guide/advanced/fixed-packages.md +++ b/site/guide/advanced/fixed-packages.md @@ -47,4 +47,4 @@ For example: It will match all packages starting with `pkg-`. -**The glob expressions must be defined according to the [micromatch](https://www.npmjs.com/package/micromatch) format.** +**The glob expressions must be defined according to the [picomatch](https://npmx.dev/picomatch) format.** diff --git a/site/guide/advanced/linked-packages.md b/site/guide/advanced/linked-packages.md index c7f049e02..a9cd3dac0 100644 --- a/site/guide/advanced/linked-packages.md +++ b/site/guide/advanced/linked-packages.md @@ -87,4 +87,4 @@ For example: It will match all packages starting with `pkg-`. -**The glob expressions must be defined according to the [micromatch](https://www.npmjs.com/package/micromatch) format.** +**The glob expressions must be defined according to the [picomatch](https://npmx.dev/picomatch) format.** diff --git a/site/guide/basic/configuration.md b/site/guide/basic/configuration.md index e69119d4c..ad06aa8f3 100644 --- a/site/guide/basic/configuration.md +++ b/site/guide/basic/configuration.md @@ -80,7 +80,7 @@ There are two caveats to this. These restrictions exist to ensure your repository or published code do not end up in a broken state. For a more detailed intricacies of publishing, check out our guide on [problems publishing in monorepos](../advanced/publishing-in-monorepos.md). > [!TIP] -> You can also provide glob expressions to match the packages, according to the [micromatch](https://www.npmjs.com/package/micromatch) format. +> You can also provide glob expressions to match the packages, according to the [picomatch](https://npmx.dev/picomatch) format. ## `fixed` (array of arrays of package names) From c4207414d7abcbcb9d35fff6eef433968c89574e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20Burzy=C5=84ski?= Date: Wed, 13 May 2026 09:04:56 +0200 Subject: [PATCH 14/80] packageManager with h4sh --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index b187c9e6d..d522f5911 100644 --- a/package.json +++ b/package.json @@ -61,4 +61,4 @@ "engines": { "node": "^22.11 || ^24 || >=26" } -} \ No newline at end of file +} From eaf15a5ed796c851d96afd9735ce5ecab9b8e8d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20Burzy=C5=84ski?= Date: Wed, 13 May 2026 09:05:47 +0200 Subject: [PATCH 15/80] update local node version --- .node-version | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.node-version b/.node-version index 620c5e1e9..54c65116f 100644 --- a/.node-version +++ b/.node-version @@ -1 +1 @@ -v22.9.0 +v24 From 1b9b483cd46bfe6eedabdc230e61dcd1835a7e96 Mon Sep 17 00:00:00 2001 From: bluwy Date: Mon, 18 May 2026 11:18:40 +0800 Subject: [PATCH 16/80] Fix lint --- eslint.config.mjs | 1 + pnpm-workspace.yaml | 6 +++--- site/package.json | 2 +- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/eslint.config.mjs b/eslint.config.mjs index d737da340..6ee5a900d 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -12,6 +12,7 @@ export default defineConfig( "**/node_modules/**", "**/dist/**", "packages/cli/bin.js", + "site/.vitepress/cache/**", "**/*.snap", ], }, diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 8c4219b23..8db33e450 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -13,9 +13,9 @@ minimumReleaseAge: 10080 overrides: rolldown: 1.0.0 - 'vitepress>@docsearch/js': '-' - 'vitepress>@docsearch/sidepanel-js': '-' - 'vitepress>vite': ^8.0.0 + "vitepress>@docsearch/js": "-" + "vitepress>@docsearch/sidepanel-js": "-" + "vitepress>vite": ^8.0.0 shellEmulator: true trustPolicy: no-downgrade diff --git a/site/package.json b/site/package.json index 2d4c454cc..9c04a58b2 100644 --- a/site/package.json +++ b/site/package.json @@ -1,7 +1,7 @@ { "name": "@changesets/docs", - "private": true, "version": "0.0.1", + "private": true, "description": "The official documentation for Changesets", "type": "module", "scripts": { From 1a410a1951bd52318e54130e84f6b04e3d84073f Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 20 May 2026 00:42:01 +0800 Subject: [PATCH 17/80] Rewrite intro pages - rewrite getting-started - rewrite concepts -> origins - rewrite common-questions -> faq - delete what-are-changesets (covered in getting-started) - delete dictionary (explain everything inline where possible) --- site/.vitepress/config.ts | 9 ++- site/faq.md | 50 +++++++++++++ site/guide/introduction/common-questions.md | 30 -------- site/guide/introduction/concepts.md | 61 --------------- site/guide/introduction/dictionary.md | 34 --------- site/guide/introduction/getting-started.md | 75 +++++++------------ site/guide/introduction/origins.md | 60 +++++++++++++++ .../guide/introduction/what-are-changesets.md | 16 ---- 8 files changed, 142 insertions(+), 193 deletions(-) create mode 100644 site/faq.md delete mode 100644 site/guide/introduction/common-questions.md delete mode 100644 site/guide/introduction/concepts.md delete mode 100644 site/guide/introduction/dictionary.md create mode 100644 site/guide/introduction/origins.md delete mode 100644 site/guide/introduction/what-are-changesets.md diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts index 5a5d1b232..6f6f90a15 100644 --- a/site/.vitepress/config.ts +++ b/site/.vitepress/config.ts @@ -73,6 +73,10 @@ export default defineConfig({ text: "Guide", link: "/guide/introduction/getting-started", }, + { + text: "FAQ", + link: "/faq", + }, { text: "Resources", items: [ @@ -108,11 +112,8 @@ export default defineConfig({ text: "Introduction", base: "/guide/introduction/", items: [ - { text: "What are Changesets?", link: "what-are-changesets" }, { text: "Getting Started", link: "getting-started" }, - { text: "Common Questions", link: "common-questions" }, - { text: "Concepts", link: "concepts" }, - { text: "Dictionary", link: "dictionary" }, + { text: "Origins", link: "origins" }, ], }, { diff --git a/site/faq.md b/site/faq.md new file mode 100644 index 000000000..4196d3172 --- /dev/null +++ b/site/faq.md @@ -0,0 +1,50 @@ +# Frequently Asked Questions + +Check the [guide](./guide/introduction/getting-started.md) for more detailed explanations of Changesets. + +## What is a changeset? + +A changeset is a Markdown file that describes a change, and includes YAML frontmatter that describes the packages affected with the respective [semver](https://semver.org) bump types. + +Changesets are automatically generated via the CLI: + +::: code-group + +```bash [npm] +$ npx @changesets/cli +``` + +```bash [pnpm] +$ pnpm changeset +``` + +```bash [yarn] +$ yarn changeset +``` + +::: + +They typically look like this: + +```md +--- +"pkg-a": minor +"pkg-b": patch +--- + +Summary of the change +``` + +## Do I need a changeset for every change? + +No! Since a changeset describes how a change should be released, changes that don't require a release do not need a changeset. + +## Can I manually edit a changeset? + +Yes! You can edit the file name, Markdown summary, and YAML frontmatter package names and bump types after they're created or committed. The file name uses random human readable names by default to avoid collisions, but there's no harm in renaming them. + +You can also delete them if you feel the changeset is not needed for a previous change as long as it has not been released yet. + +## Are changesets removed? + +When `changeset version` is run, all changeset files are moved. This is so we only ever use a changeset once. This makes the `.changeset` folder a very bad place to store any other information. diff --git a/site/guide/introduction/common-questions.md b/site/guide/introduction/common-questions.md deleted file mode 100644 index d2e719a15..000000000 --- a/site/guide/introduction/common-questions.md +++ /dev/null @@ -1,30 +0,0 @@ -# Common Questions - -A quick list of common questions you might want answered to understand what changesets is doing, without going into minutiae or workflow. - -## Changesets are automatically generated - -Changesets are generated by the `yarn changeset` or `npx @changesets/cli` command. As long as you are following a changeset release flow, you shouldn't have any problems. - -## Each changeset is its own file - -We use random human readable names by default for these files to avoid collisions when generating them, but there's no harm that will come from renaming them. - -## Changesets are automatically removed - -When `changeset version` or equivalent command is run, all the changeset files are removed. This is so we only ever use a changeset once. This makes the `.changeset` folder a very bad place to store any other information. - -## Changesets are markdown files with YAML front matter - -The two parts of the file are for different purposes. You should feel free to edit both parts as much as you want. - -- The markdown text is a summary of the changes that will be prepended to your changelog when you next run your version command. -- The YAML front matter describes what should be versioned by the version command - -## I want to edit the summary or package bump types - is it safe to do that? - -Editing the summary or package bump types is completely safe. You can even write changesets without the command if you want. - -## Can I manually delete changesets? - -You can, but you should be aware this will remove the intent to release communicated by the changeset, and should be done with caution. diff --git a/site/guide/introduction/concepts.md b/site/guide/introduction/concepts.md deleted file mode 100644 index de4ac8b5e..000000000 --- a/site/guide/introduction/concepts.md +++ /dev/null @@ -1,61 +0,0 @@ -# A Detailed Explanation of Changesets - -Below, you will find a detailed explanation of what changesets are, and how they are being thought about. - -## The problem: - -When organising the release of packages, you may end up wanting to group several changes together written by different people and/or over a relatively large period of time. The best time to capture this information is when submitting a PR (when it is fresh in your mind), not when you eventually go to batch and release these changes. - -Git is a bad place to store this information, as it discourages writing detailed change descriptions - you want to allow people to provide as much documentation for the change as they want. - -## The solution, Changesets: - -The best way to think about a changeset as separate to either a changelog or a version bump is that a changeset is an 'intent to change'. The intent to change carries with it two key bits of information: - -- versioning -- changelogs - -As it is an intent to change, the relevant versioning information is: - -- 'major' | 'minor' | 'patch' - -In addition, within a mono-repository, we can encode information about any other packages in the mono-repository that should be re-released to consume this change. This ensures that if you upgrade latest of all the packages, they are all compatible. The current implementation is heavily informed by [bolt's](https://github.com/boltpkg/bolt) opinion on version compatibility. - -- changelog information can be stored as a markdown snippet. - -As storing this information directly in git is problematic, we store it in the file system using the following structure: - -``` --| .changeset/ --|-| UNIQUE_ID.md -``` - -A changeset is a Markdown file with YAML front matter. The contents of the Markdown is the change summary which will be written to the changelog and the YAML front matter describes what packages have changed and what semver bump types they should be - -```md ---- -"@myproject/cli": major -"@myproject/core": minor ---- - -Change all the things -``` - -This is useful because it breaks versioning into two steps: - -1. Adding a changeset - can be done in a PR, by a contributor, while the change is fresh in their mind. -2. Versioning - combines all changesets, creates one version bump for each package based on the maximum version bump of each package, updates dependencies where needed, and writes changelogs. Can then be reviewed as an aggregate. - -## The tooling that makes this worthwhile - -1. CLI generation of new changesets. -2. Automated consumption of changesets to do versioning. -3. Detection + surfacing of changesets in PRs. - -A tool to publish multiple packages from a mono-repo is also important, however does not need to be linked to this. - -## Benefits to single-package repos - -Changesets are designed first and foremost to handle versioning in multi-package repos, where interdependencies flowing through the system are important to understand and capture. - -Conceptually though, the benefits of changesets are detachable from this. I think this process overall leads to an improvement in Pull Requests that helps increase confidence in versioning decisions and changelog entries. diff --git a/site/guide/introduction/dictionary.md b/site/guide/introduction/dictionary.md deleted file mode 100644 index 3872915ba..000000000 --- a/site/guide/introduction/dictionary.md +++ /dev/null @@ -1,34 +0,0 @@ -# Changesets Dictionary - -This is a list of some words and phrases that are used in changesets which are helpful to know so that contributors to changesets have a shared understanding of various concepts in the project. - -Several of these have associated type definitions, which you can find in [our types package](https://github.com/changesets/changesets/blob/main/packages/types). - -- **changeset** - an intent to release a set of packages at particular bump types with a summary of the changes made. Changesets are stackable, that is running `bump` will apply any number of changesets correctly. Changesets are used to generate further information, such as the `release information`, and the `release plan`. -- **summary** - Information about the changes the changeset represents - this is written out to the `CHANGELOG.md` file of every package mentioned in the changeset. -- **changeset folder** - A `./changeset` folder - this is where we store written versions of changesets. Currently we assume all changesets are written to this. -- **workspace** - a local package in a multi-package repo -- **bump-type** - The type of change expected. Of type `major | minor | patch | none`, based on the change types of [semver](https://semver.org/) -- **range-type** - The type of range a package depends on, such as `1.0.0`, `~1.0.0`, or `^1.0.0`. This is a subset of valid semver ranges as [defined by node](https://github.com/npm/node-semver#ranges), narrowing to ranges we can update programmatically. -- **bump** - - (1) The command to apply all current changesets and update all package versions and changelogs. - - (2) The act of updating a package version to a new version. -- **single-package repo** - A repository which only contains a single package which is at the root of the repo -- **multi-package repo/monorepo** - A repository which contains multiple packages, generally managed by [Bolt](https://github.com/boltpkg/bolt) or [Yarn Workspaces](https://yarnpkg.com/lang/en/docs/workspaces/). -- **release line generators** - The `getReleaseLine` and `getDependencyReleaseLine` functions which are responsible for creating the lines inserted into changelog. A changelog entry for a particular release can be thought of as `releaseLineGenerators(changesets)` -- **fixed packages** - Fixed packages share a semver categorisation, such that all fixed packages have the same semver version and are always published together. The logistics of this are best left to our [fixed-packages](../advanced/fixed-packages.md) documentation. -- **linked packages** - Linked packages share a semver categorisation, such that all published linked packages have consistent new semver ranges. The logistics of this are best left to our [linked-packages](../advanced/linked-packages.md) documentation. -- **release instruction** An object containing an intent to release a single package, consisting of the package name and a bump type -- **release plan** - A calculated object that shows everything a collection of changesets will release, and at what version, and how. This object includes a calculation of dependencies, and considerations for `linked` packages. -- **absolutely correct semver** - making semver versioning decisions to ensure nothing less than major is capable of breaking a consumer's code. Because literally any change is technically capable of breaking a user's code, absolutely correct semver requires that all changes are major changes. -- **pragmatically correct semver** - Making semver decisions that you believe to be correct, but may be in error. A pragmatic assessment is likely to change with the number of users of a project, and the API surface area of the project. Whenever we talk about 'correct semver', we are referring to 'pragmatically correct semver' -- **dependency** - A package that is depended upon by another given package. -- **dependent** - A package which depends on another given package. This is frequently used in the context of getting the dependents of a package so they can be released. -- **release** - The combination of versioning and publishing a package or packages which may include a build process before publishing -- **prereleases** - A pre-release is a release that uses a tag, and is not published as `latest` on npm. This is designed for when you want to share code, but are not yet ready for it to be the main package used by everyone. Pre-releases for packages are common, but pre-releases within a monorepo presents unique problems. You can see our exhaustive pre-release documentation [in our prereleases documentation](../advanced/prereleases.md). In addition, there are two different approaches to pre-releases which are defined for use separately. -- **Release Candidate (RC) prerelease** - An RC prerelease is done before an intended important release, likely a major release. It includes semver information about what the next intended release version is, a tag, and an iterated number for the prerelease. The output of this is intended to be committed, and then further work done on the branch. An example would be if I am on `1.0.0` of a package, and I want to do an RC for the next `major` version we would have: `package-one@2.0.0-my-tag.0`, and then the next publish is `package-one@2.0.0-my-tag.1`. -- **snapshot prerelease** - A snapshot pre-release is intended to make it easy to test all changes at a particular git commit. It is published at `0.0.0` and uses the git hash as the tag. This should be used as a less formal method than a release candidate to make it easy to install and test changes. An example, if we have a package at `1.0.0`, and have a changeset for it to be `major` bumped, a snapshot release will be at `0.0.0-ABCDEFGH` (the last github hash). If we add more commits, the next snapshot would be `0.0.0-HIJKLMNOP`. - -## Things that we haven't figured out how to explain well yet - -- The fact that a package is depending on a package and what the range of the dependency is specified in the list of the package's dependencies. This is specifically not about the dependency but about the relationship between the dependent and the dependency. diff --git a/site/guide/introduction/getting-started.md b/site/guide/introduction/getting-started.md index 3aa89db68..8d38710fa 100644 --- a/site/guide/introduction/getting-started.md +++ b/site/guide/introduction/getting-started.md @@ -1,102 +1,81 @@ -# Using Changesets +# Getting Started -Changesets are designed to make your workflows easier, by allowing the person making contributions to make key decisions when they are making their contribution. Changesets hold two key bits of information: a version type (following [semver](https://semver.org/)), and change information to be added to a changelog. +## What is Changesets? -In addition, changesets were originally designed for implementation in [bolt monorepos](https://github.com/boltpkg/bolt). As such, in a monorepo context, changesets will handle bumping dependencies of changed packages, if that is required. +Changesets has several meanings that are sometimes used interchangeably: -This guide is aimed at package maintainers adding changesets as a tool. For the information relevant to contributors, see [adding a changeset](../basic/adding-a-changeset.md). +1. It is a tool to manage package versions and changelog generation in a project. It is designed to work in [monorepos](https://monorepo.tools) as well as single package repos. -The overall tool after initialization should lead to a loop that looks like: +2. It is also a workflow that allows contributors to describe what their changes are and how they should be released. -1. Changesets added along with each change -2. The version command is run when a release is ready, and the changes are verified -3. The publish command is run afterwards. +3. A change description is also known as a "changeset". Typically represented as markdown file, it records the affected packages, the type of change following [semver](https://semver.org), and the change summary to be added to the changelog. -The second two steps can be made part of a CI process. +
-## Add the changeset tool +The Changesets development loop looks like this: -::: code-group - -```bash [npm] -$ npm install --save-dev @changesets/cli && npx @changesets/cli init -``` +1. When making a change, e.g. via a git commit or a PR, a changeset is added alongside. +2. When a release is ready, the version command is run which consumes all the changesets and updates the package versions and changelogs. +3. Then, the publish command is run to publish the new versions of packages. -```bash [pnpm] -$ pnpm add -D @changesets/cli && pnpm changeset init -``` - -```bash [yarn] -$ yarn add -D @changesets/cli && yarn changeset init -``` - -::: +The last two steps can be automated in CI. -## Adding changesets +## Setting Up ::: code-group ```bash [npm] -$ npx @changesets/cli +$ npm install --save-dev @changesets/cli ``` ```bash [pnpm] -$ pnpm changeset +$ pnpm add -D @changesets/cli ``` ```bash [yarn] -$ yarn changeset +$ yarn add -D @changesets/cli ``` ::: -> [!NOTE] -> You can run `changeset add` to add a changeset if you want to, but running Changesets without any command works as well. - -## Versioning and publishing - -Once you decide you want to do a release, you can run +Next, run `init` to set up the `.changeset` folder in your project: ::: code-group ```bash [npm] -$ npx @changesets/cli version +$ npx @changesets/cli init ``` ```bash [pnpm] -$ pnpm changeset version +$ pnpm changeset init ``` ```bash [yarn] -$ yarn changeset version +$ yarn changeset init ``` ::: -This consumes all changesets, and updates to the most appropriate semver version based on those changesets. It also writes changelog entries for each consumed changeset. - -We recommend at this step reviewing both the changelog entries and the version changes for packages. Once you are confident that these are correct, and have made any necessary tweaks to changelogs, you can publish your packages: +Now, whenever you make a change, you can create a changeset through the CLI: ::: code-group ```bash [npm] -$ npx @changesets/cli publish +$ npx @changesets/cli ``` ```bash [pnpm] -$ pnpm changeset publish +$ pnpm changeset ``` ```bash [yarn] -$ yarn changeset publish +$ yarn changeset ``` ::: -This will run npm publish in each package that is of a later version than the one currently listed on npm. +::: tip Not every change requires a changeset -## Some handy advice +Since a changeset describes how a change should be released, changes that don't require a release do not need a changeset. As such, it is **not recommended** to block contributions in the absence of a changeset. -### Not every change requires a changeset - -Since changesets are focused on releases and changelogs, changes to your repository that don't require these won't need a changeset. As such, we recommend not adding a blocking element to contributions in the absence of a changeset. +::: diff --git a/site/guide/introduction/origins.md b/site/guide/introduction/origins.md new file mode 100644 index 000000000..00d1e8d6b --- /dev/null +++ b/site/guide/introduction/origins.md @@ -0,0 +1,60 @@ +# Origins + +## The Problem + +When organising the release of packages, you may end up wanting to group several changes together written by different people and/or over a relatively large period of time. The best time to capture this information is when submitting a PR (when it is fresh in your mind), not when you eventually go to batch and release these changes. + +Git is a bad place to store this information, as it discourages writing detailed change descriptions. You want to allow people to provide as much documentation for the change as they want. + +## The Solution, Changesets + +The best way to think about a changeset as separate to either a changelog or a version bump is that a changeset is an "intent to change", carrying two key bits of information: **versioning** and **changelogs**. + +### Versioning + +The versioning information can be represented with [semver](https://semver.org) as major, minor, or patch. + +In a monorepo, we can also encode information about any other packages that should be re-released as part of this change. This ensures that if you upgrade to the latest of all the packages, they are all compatible. The current implementation is heavily informed by [bolt](https://github.com/boltpkg/bolt)'s opinion on version compatibility. + +### Changelogs + +The changelog information can be stored as a Markdown snippet. + +As storing this information directly in git is problematic, we store it in the filesystem using the following structure: + +``` + | .changeset/ + | |- UNIQUE_ID.md +``` + +## The Result + +A changeset is a Markdown file with YAML frontmatter. The contents of the Markdown is the change summary which will be written to the changelog and the YAML frontmatter describes the packages have changed and their respective semver bump types: + +```md +--- +"@myproject/cli": major +"@myproject/core": minor +--- + +Change all the things +``` + +This is useful because it breaks versioning into two steps: + +1. Adding a changeset - can be done in a PR, by a contributor, while the change is fresh in their mind. +2. Versioning - combines all changesets, creates one version bump for each package based on the maximum version bump of each package, updates dependencies where needed, and writes changelogs. Can then be reviewed as an aggregate. + +## The Tooling that Makes this Worthwhile + +1. CLI generation of new changesets. +2. Automated consumption of changesets to do versioning. +3. Detection + surfacing of changesets in PRs. + +A tool to publish multiple packages from a monorepo is also important, however does not need to be linked to this. + +## Benefits for Single Package Repos + +Changesets are designed first and foremost to handle versioning in monorepos, where interdependencies flowing through the system are important to understand and capture. + +Conceptually though, the benefits of changesets are detachable from this. The workflow overall leads to an improvement in pull requests that helps increase confidence in versioning decisions and changelog entries. diff --git a/site/guide/introduction/what-are-changesets.md b/site/guide/introduction/what-are-changesets.md deleted file mode 100644 index fe3863e98..000000000 --- a/site/guide/introduction/what-are-changesets.md +++ /dev/null @@ -1,16 +0,0 @@ -# What are changesets? - - - -The changesets workflow is designed to help when people are making changes, all the way through to publishing. It lets contributors declare how their changes should be released, then we automate updating `package versions`, and `changelogs`, and `publishing new versions` of packages based on the provided information. - -Changesets has a focus on solving these problems for multi-package repositories, and keeps packages that rely on each other within the multi-package repository up-to-date, as well as making it easy to make changes to groups of packages. - -> [!NOTE] -> Just want to try it out? Skip to the [Getting Started](./getting-started.md) page. - -## How do we do that? - -A changeset is an intent to release a set of packages at particular semver bump types with a summary of the changes made. - -The `@changesets/cli` package allows you to write changeset files as you make changes, then combine `any number of changesets` into a release, that flattens the bump-types into a single release per package, handles internal dependencies in a multi-package-repository, and updates changelogs, as well as release all updated packages from a mono-repository with one command. From 17f7e5fefc2f99faebef83929673bfec7151fc8f Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 20 May 2026 00:49:05 +0800 Subject: [PATCH 18/80] Fix site build --- site/guide/basic/adding-a-changeset.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/guide/basic/adding-a-changeset.md b/site/guide/basic/adding-a-changeset.md index 031d9e486..88758a9ce 100644 --- a/site/guide/basic/adding-a-changeset.md +++ b/site/guide/basic/adding-a-changeset.md @@ -68,4 +68,4 @@ Changesets are designed to stack, so there's no problem with adding multiple. Yo ## I want to know more about changesets -[here is a more in-depth explanation](../introduction/concepts.md) +[here is a more in-depth explanation](../introduction/origins.md) From 574bcb6b64c0edef05b56e434e21002cf4ba4edc Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 20 May 2026 10:44:20 +0800 Subject: [PATCH 19/80] Tweak styles --- site/.vitepress/theme/custom.css | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/site/.vitepress/theme/custom.css b/site/.vitepress/theme/custom.css index de3fe4e10..b770455e2 100644 --- a/site/.vitepress/theme/custom.css +++ b/site/.vitepress/theme/custom.css @@ -37,16 +37,29 @@ } /* Ensure tagline stays single line */ -.VPHero .container .main > .heading > .text { +.VPHero .heading > .text { font-size: 48px; } +/* Loosen heading in mobile view */ +@media (max-width: 768px) { + .VPHero .heading > .name, + .VPHero .heading > .text { + letter-spacing: 0px; + } +} + /* Blur effect for navigation bars */ .VPNavBar:not(.home.top), .VPLocalNav { backdrop-filter: saturate(180%) blur(20px); } +/* We do not need sponsor images for now */ +.VPHomeSponsors .sponsors { + display: none; +} + .VPFeature .details > a { color: var(--vp-c-text-1); text-decoration: underline; From 1f311e11557a12754371a463d4a3b52e3199a569 Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 20 May 2026 11:25:51 +0800 Subject: [PATCH 20/80] Improve faq --- site/.vitepress/config.ts | 1 - site/faq.md | 49 +++++++++++++----- site/guide/basic/adding-a-changeset.md | 71 -------------------------- site/guide/introduction/origins.md | 8 +-- 4 files changed, 40 insertions(+), 89 deletions(-) delete mode 100644 site/guide/basic/adding-a-changeset.md diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts index 6f6f90a15..2bbffdfb7 100644 --- a/site/.vitepress/config.ts +++ b/site/.vitepress/config.ts @@ -120,7 +120,6 @@ export default defineConfig({ text: "Basic", base: "/guide/basic/", items: [ - { text: "Adding a Changeset", link: "adding-a-changeset" }, { text: "Checking for Changesets", link: "checking-for-changesets", diff --git a/site/faq.md b/site/faq.md index 4196d3172..dd2de03c8 100644 --- a/site/faq.md +++ b/site/faq.md @@ -4,9 +4,24 @@ Check the [guide](./guide/introduction/getting-started.md) for more detailed exp ## What is a changeset? -A changeset is a Markdown file that describes a change, and includes YAML frontmatter that describes the packages affected with the respective [semver](https://semver.org) bump types. +A changeset is a Markdown file that describes a change, and includes YAML frontmatter that describes the affected packages with the respective [semver](https://semver.org) bump types. They typically look like this: -Changesets are automatically generated via the CLI: +```md +--- +"pkg-a": minor +"pkg-b": patch +--- + +Summary of the change +``` + +## Do I need a changeset for every change? + +No! Since a changeset describes how a change should be released, changes that don't require a release do not need a changeset. + +## How do I add a changeset? + +Run the CLI to generate a changeset: ::: code-group @@ -24,20 +39,28 @@ $ yarn changeset ::: -They typically look like this: +And follow the prompts: -```md ---- -"pkg-a": minor -"pkg-b": patch ---- +1. If the project has multiple packages, select the packages you want to include. + - Use ↑ and ↓ to navigate to packages + - Press space to select a package. + - Press enter when all desired packages are selected. +2. Select the appropriate [semver](https://semver.org) bump type for each selected package. +3. Provide a message to go alongside the changeset. This will be written into the changelog when the next release occurs. -Summary of the change -``` + While not every changeset is going to need a huge amount of detail, a good idea of what should be in a changeset is: + - WHAT the change is + - WHY the change was made + - HOW a consumer should update their code -## Do I need a changeset for every change? +A new changeset file will be created in the `.changeset` folder. Once you are happy with the changeset, commit the file to your branch. -No! Since a changeset describes how a change should be released, changes that don't require a release do not need a changeset. +## Can I add more than one changeset in a PR? + +Yes! Changesets are designed to stack, so there's no problem with adding multiple. You might want to add more than one changeset when: + +- You want to release multiple packages with different changelog entries +- You have made multiple changes to a package that should each be called out separately ## Can I manually edit a changeset? @@ -47,4 +70,4 @@ You can also delete them if you feel the changeset is not needed for a previous ## Are changesets removed? -When `changeset version` is run, all changeset files are moved. This is so we only ever use a changeset once. This makes the `.changeset` folder a very bad place to store any other information. +When `changeset version` is run, all changeset files are removed. This is so we only ever use a changeset once. This makes the `.changeset` folder a very bad place to store any other information. diff --git a/site/guide/basic/adding-a-changeset.md b/site/guide/basic/adding-a-changeset.md deleted file mode 100644 index 88758a9ce..000000000 --- a/site/guide/basic/adding-a-changeset.md +++ /dev/null @@ -1,71 +0,0 @@ -# Adding a changeset - -Hi! You might be here because a person or a bot has asked you to 'add a changeset' to a project. Let's walk through adding a changeset. But first, what is a changeset? - -## What is a changeset? - -A changeset is a piece of information about changes made in a branch or commit. It holds three bits of information: - -- What we need to release -- What version we are releasing packages at (using a [semver bump type](https://semver.org/)) -- A changelog entry for the released packages - -## I am in a multi-package repository (a mono-repo) - -1. Run the command line script `yarn changeset` or `pnpm changeset` or `npx @changesets/cli`. -2. Select the packages you want to include in the changeset using ↑ and ↓ to navigate to packages, and space to select a package. Hit enter when all desired packages are selected. -3. You will be prompted to select a bump type for each selected package. Select an appropriate bump type for the changes made. See [here](https://semver.org/) for information on semver versioning -4. Your final prompt will be to provide a message to go alongside the changeset. This will be written into the changelog when the next release occurs. - -After this, a new changeset will be added which is a markdown file with YAML front matter. - -``` --| .changeset/ --|-| UNIQUE_ID.md -``` - -The message you typed can be found in the markdown file. If you want to expand on it, you can write as much markdown as you want, which will all be added to the changelog on publish. If you want to add more packages or change the bump types of any packages, that's also fine. - -While not every changeset is going to need a huge amount of detail, a good idea of what should be in a changeset is: - -- WHAT the change is -- WHY the change was made -- HOW a consumer should update their code - -5. Once you are happy with the changeset, commit the file to your branch. - -## I am in a single-package repository - -1. Run the command line script `yarn changeset` or `pnpm changeset` or `npx @changesets/cli`. -2. Select an appropriate bump type for the changes made. See [here](https://semver.org/) for information on semver versioning. -3. Your final prompt will be to provide a message to go alongside the changeset. This will be written into the changelog when the next release occurs. - -After this, a new changeset will be added which is a markdown file with YAML front matter. - -``` --| .changeset/ --|-| UNIQUE_ID.md -``` - -The message you typed can be found in the markdown file. If you want to expand on it, you can write as much markdown as you want, which will all be added to the changelog on publish. If you want to change the bump type for the changeset, that's also fine. - -While not every changeset is going to need a huge amount of detail, a good idea of what should be in a changeset is: - -- WHAT the change is -- WHY the change was made -- HOW a consumer should update their code - -4. Once you are happy with the changeset, commit the file to your branch. - -## Tips on adding changesets - -### You can add more than one changeset to a pull request - -Changesets are designed to stack, so there's no problem with adding multiple. You might want to add more than one changeset when: - -- You want to release multiple packages with different changelog entries -- You have made multiple changes to a package that should each be called out separately - -## I want to know more about changesets - -[here is a more in-depth explanation](../introduction/origins.md) diff --git a/site/guide/introduction/origins.md b/site/guide/introduction/origins.md index 00d1e8d6b..39bbac0a0 100644 --- a/site/guide/introduction/origins.md +++ b/site/guide/introduction/origins.md @@ -2,7 +2,7 @@ ## The Problem -When organising the release of packages, you may end up wanting to group several changes together written by different people and/or over a relatively large period of time. The best time to capture this information is when submitting a PR (when it is fresh in your mind), not when you eventually go to batch and release these changes. +When organizing the release of packages, you may end up wanting to group several changes together written by different people and/or over a relatively large period of time. The best time to capture this information is when submitting a PR (when it is fresh in your mind), not when you eventually go to batch and release these changes. Git is a bad place to store this information, as it discourages writing detailed change descriptions. You want to allow people to provide as much documentation for the change as they want. @@ -33,11 +33,11 @@ A changeset is a Markdown file with YAML frontmatter. The contents of the Markdo ```md --- -"@myproject/cli": major -"@myproject/core": minor +"pkg-a": minor +"pkg-b": patch --- -Change all the things +Summary of the change ``` This is useful because it breaks versioning into two steps: From 5d7fa3b4ffac8876673b0888bde92de71d2660eb Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 20 May 2026 17:22:08 +0800 Subject: [PATCH 21/80] Update automating-changesets --- site/.vitepress/config.ts | 3 ++ site/guide/advanced/snapshot-releases.md | 2 +- site/guide/basic/automating-changesets.md | 54 +++++++++++----------- site/guide/introduction/getting-started.md | 4 +- 4 files changed, 34 insertions(+), 29 deletions(-) diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts index 2bbffdfb7..c8ddf93f8 100644 --- a/site/.vitepress/config.ts +++ b/site/.vitepress/config.ts @@ -62,6 +62,9 @@ export default defineConfig({ search: { provider: "local", }, + outline: { + level: [2, 3], + }, footer: { message: `This site is powered by ${netlifyLink}`, diff --git a/site/guide/advanced/snapshot-releases.md b/site/guide/advanced/snapshot-releases.md index cbce2edb8..2914db976 100644 --- a/site/guide/advanced/snapshot-releases.md +++ b/site/guide/advanced/snapshot-releases.md @@ -4,7 +4,7 @@ Snapshot releases are a way to release your changes for testing without updating ## Starting Off -Create changesets as normal, as described in [adding a changeset](../basic/adding-a-changeset.md). When you are ready to release a snapshot, you should make a dedicated branch for doing so. +Create changesets as normal. When you are ready to release a snapshot, you should make a dedicated branch for doing so. ## Versioning your packages diff --git a/site/guide/basic/automating-changesets.md b/site/guide/basic/automating-changesets.md index 51d573f75..74d0aa8ec 100644 --- a/site/guide/basic/automating-changesets.md +++ b/site/guide/basic/automating-changesets.md @@ -1,67 +1,69 @@ # Automating Changesets -While changesets are designed to work with a fully manual process, it also provides tools to help automate these releases. These can be broken into two major decisions: +While Changesets is designed to work with a fully manual process, it also provides tools to help automate these releases. These can be broken into two major decisions: -1. How do I want to ensure pull requests have changesets? +1. How do I ensure pull requests have changesets? 2. How do I run the version and publish commands? -Here we have a quick-start recommended workflow, with more +Here is a quick-start recommended workflow and more customization details. ## Recommended Automation Flow -1. Install our [changeset bot](https://github.com/apps/changeset-bot) into your repository. -2. Add the [github action](https://github.com/changesets/action) to your repository. +1. Install the [Changesets GitHub Bot](https://github.com/apps/changeset-bot) into your repository. +2. Add the [Changesets GitHub Action](https://github.com/changesets/action) to your repository. -## How do I want to ensure pull requests have changesets? +## How do I ensure pull requests have changesets? -Changesets are committed to files, so a diligent reviewer can always technically tell if a changeset is absent and request one be added. As humans though, a file not being there is easy to miss. We recommend adding some way to detect the presence or absence of changesets on a pull request so you don't have to, as well as highlight it to pull-request makers so you don't have to. +Changesets are committed to files, so a diligent reviewer can always technically tell if a changeset is absent and request one to be added. As humans though, a file not being there is easy to miss. + +We recommend adding some way to detect the presence or absence of changesets on a pull request so you don't have to, as well as highlight it directly to the pull request author. This has two main approaches. ### Non-blocking -In this approach, a pull request may be merged if no changeset is present, and a missing changeset does not create a red build. Our [github changeset bot](https://github.com/apps/changeset-bot) is the best way to prompt for changesets without making them blocking. As a handy extra feature, they give you a link to add your own changeset as a maintainer to smooth over merging pull requests without waiting for the contributor to add a changeset. +In this approach, a pull request may be merged if no changeset is present, and a missing changeset does not cause a failure in CI. Our [Changesets GitHub Bot](https://github.com/apps/changeset-bot) is the best way to prompt for changesets without making them blocking. -### Blocking +It comments on PRs of whether changesets are present and gives you link to add your own changeset as a maintainer to smooth over merging pull requests without waiting for the contributor to add a changeset. -Sometimes, you may want to make CI fail if no changeset is present to ensure no PR can be merged without a changeset. To do this: +### Blocking -In your CI process, add a step that runs: +As not every change requires a release, we **do not recommend** blocking contributions in the absence of a changeset. However, if you prefer a consistent process that always requires a changeset, you can add a step in your CI setup that runs: ::: code-group ```bash [npm] -$ npx @changesets/cli status --since=main +$ npx @changesets/cli status --since main ``` ```bash [pnpm] -$ pnpm changeset status --since=main +$ pnpm changeset status --since main ``` ```bash [yarn] -$ yarn changeset status --since=main +$ yarn changeset status --since main ``` ::: -This will exit with exit code 1 if there have been no new changesets since main. +This will exit with exit code 1 if there have been no new changesets since the `main` branch. -In some cases, you may _want_ to merge a change without doing any releases (such as when you only change tests or build tools). In this case, you can run `changeset --empty`. This will add a special changeset that does not release anything. +If you want to merge a change without doing any releases (such as when you only change tests or build tools), you can run `changeset --empty` to add a special changeset that does not release anything. ## How do I run the version and publish commands? -We have a [github action](https://github.com/changesets/action) that +You can set up the [Changesets GitHub Action](https://github.com/changesets/action) to automate this process: -- creates a `version` PR, then keeps it up to date, recreating it when merged. This PR always has an up-to-date run of `changeset version` -- Optionally allows you to do releases when changes are merged to the base branch. +- It creates a `version` PR, then keeps it up to date, recreating it when merged. +- Optionally, if publishing is set up, it automatically publishes the release whenever the PR is merged. -If you don't want to use this action, the manual workflow we recommend for running the `version` and `publish` commands is: +If you do not want to use this action, the manual workflow we recommend is: -- A release coordinator (RC) calls to stop any merging to the base branch -- The RC pulls down the base branch, runs `changeset version`, then makes a new PR with the versioning changes -- The versioning changes are merged back into the base branch -- The RC pulls the base branch again and runs `changeset publish` -- The RC runs `git push --follow-tags` to push the release tags back -- The RC unblocks merging to the base branch +1. A release coordinator (RC) calls to stop any merging to the base branch +2. The RC pulls down the base branch, runs `changeset version`, then makes a new PR with the versioning changes +3. The versioning changes are merged back into the base branch +4. The RC pulls the base branch again and runs `changeset publish` +5. The RC runs `git push --follow-tags` to push the release tags back +6. The RC unblocks merging to the base branch This is a lot of steps and is quite finicky (we have to pull from the base branch twice). Feel free to finesse it to your own circumstances. diff --git a/site/guide/introduction/getting-started.md b/site/guide/introduction/getting-started.md index 8d38710fa..174388119 100644 --- a/site/guide/introduction/getting-started.md +++ b/site/guide/introduction/getting-started.md @@ -18,7 +18,7 @@ The Changesets development loop looks like this: 2. When a release is ready, the version command is run which consumes all the changesets and updates the package versions and changelogs. 3. Then, the publish command is run to publish the new versions of packages. -The last two steps can be automated in CI. +The last two steps can be [automated in CI](../basic/automating-changesets.md). ## Setting Up @@ -76,6 +76,6 @@ $ yarn changeset ::: tip Not every change requires a changeset -Since a changeset describes how a change should be released, changes that don't require a release do not need a changeset. As such, it is **not recommended** to block contributions in the absence of a changeset. +Since a changeset describes how a change should be released, changes that don't require a release do not need a changeset. As such, we **do not recommend** blocking contributions in the absence of a changeset. ::: From 4a60bd8d286fc923e3b1eee25199a7f3d92d67e1 Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 20 May 2026 17:30:44 +0800 Subject: [PATCH 22/80] Update acknowledgements --- site/acknowledgements.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/site/acknowledgements.md b/site/acknowledgements.md index fb839e95c..f1b53d5d0 100644 --- a/site/acknowledgements.md +++ b/site/acknowledgements.md @@ -1,11 +1,18 @@ # Acknowledgements -## Inspirations +## Thanks and Inspirations -- [bolt](https://github.com/boltpkg/bolt) - Brought us a strong concept of how packages in a mono-repo should be able to interconnect, and provided the initial infrastructure to get inter-package information. -- [Atlassian](https://www.atlassian.com/) - The original idea/sponsor of the changesets code, and where many of the ideas and processes were fermented. It was originally implemented by the team behind [atlaskit](https://atlaskit.atlassian.com). -- [lerna-semantic-release](https://github.com/atlassian/lerna-semantic-release) - put down many of the initial patterns around updating packages within a multi-package-repository, and started us thinking about how to manage dependent packages. -- [Thinkmill](https://www.thinkmill.com.au) - For sponsoring the focused open sourcing of this project, and the version two rearchitecture. +- [Bolt](https://github.com/boltpkg/bolt)\ + Brought us a strong concept of how packages in a monorepo should be able to interconnect, and provided the initial infrastructure to get inter-package information. + +- [Atlassian](https://www.atlassian.com/)\ + The original idea/sponsor of the changesets code, and where many of the ideas and processes were fermented. It was originally implemented by the team behind [Atlaskit](https://atlaskit.atlassian.com). + +- [lerna-semantic-release](https://github.com/atlassian/lerna-semantic-release)\ + Put down many of the initial patterns around updating packages within a monorepo, and started us thinking about how to manage dependent packages. + +- [Thinkmill](https://www.thinkmill.com.au)\ + For sponsoring the focused open sourcing of this project, and the version two rearchitecture. ## Cool Projects using Changesets From 633bc9c2e0f39ccdc314d1a32fb31c1f0d17cf9b Mon Sep 17 00:00:00 2001 From: bluwy Date: Thu, 21 May 2026 00:58:00 +0800 Subject: [PATCH 23/80] Update config page --- site/.vitepress/config.ts | 12 +- .../guide/advanced/publishing-in-monorepos.md | 5 - site/guide/basic/checking-for-changesets.md | 11 - site/guide/basic/configuration-file.md | 269 +++++++++++++++++ site/guide/basic/configuration.md | 271 ------------------ 5 files changed, 271 insertions(+), 297 deletions(-) delete mode 100644 site/guide/advanced/publishing-in-monorepos.md delete mode 100644 site/guide/basic/checking-for-changesets.md create mode 100644 site/guide/basic/configuration-file.md delete mode 100644 site/guide/basic/configuration.md diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts index c8ddf93f8..5f2d66dfc 100644 --- a/site/.vitepress/config.ts +++ b/site/.vitepress/config.ts @@ -123,13 +123,9 @@ export default defineConfig({ text: "Basic", base: "/guide/basic/", items: [ - { - text: "Checking for Changesets", - link: "checking-for-changesets", - }, - { text: "Automating Changesets", link: "automating-changesets" }, - { text: "Configuration", link: "configuration" }, + { text: "Configuration File", link: "configuration-file" }, { text: "CLI Reference", link: "cli" }, + { text: "Automating Changesets", link: "automating-changesets" }, ], }, { @@ -145,10 +141,6 @@ export default defineConfig({ link: "modifying-changelog-formats", }, { text: "Prereleases", link: "prereleases" }, - { - text: "Publishing in Monorepos", - link: "publishing-in-monorepos", - }, { text: "Snapshot Releases", link: "snapshot-releases" }, { text: "Versioning apps", link: "versioning-apps" }, ], diff --git a/site/guide/advanced/publishing-in-monorepos.md b/site/guide/advanced/publishing-in-monorepos.md deleted file mode 100644 index c99bf7af6..000000000 --- a/site/guide/advanced/publishing-in-monorepos.md +++ /dev/null @@ -1,5 +0,0 @@ -# Problems Publishing in Monorepos - -Monorepos have a heap of complexity around how publishing to npm works. Changesets helps most repository users avoid ever having to think about these problems, however repository maintainers, especially those who want to customise how their releases work (for example those not using our [github action](https://github.com/changesets/action/)), may want to understand what it is solving for you. - -TODO: flesh this out (sorry it's not done yet) diff --git a/site/guide/basic/checking-for-changesets.md b/site/guide/basic/checking-for-changesets.md deleted file mode 100644 index 69082de5b..000000000 --- a/site/guide/basic/checking-for-changesets.md +++ /dev/null @@ -1,11 +0,0 @@ -# Checking for changesets - -Using `@changesets/cli`, there is a `status` command. See the docs for it in the -[@changesets/cli readme](https://github.com/changesets/changesets/tree/main/packages/cli#status) - -We have a [github bot](https://github.com/apps/changeset-bot) and a -[bitbucket addon](https://bitbucket.org/atlassian/atlaskit-mk-2/src/master/build/bitbucket-release-addon/) that -alert users of missing changesets. - -If you want to cause a failure in CI on missing changesets (not recommended), you can run `changeset status --since=main`, -which will exit with a status code of 1 if there are no new changesets. diff --git a/site/guide/basic/configuration-file.md b/site/guide/basic/configuration-file.md new file mode 100644 index 000000000..7360cde96 --- /dev/null +++ b/site/guide/basic/configuration-file.md @@ -0,0 +1,269 @@ +# Configuration File + +Changesets keeps its configuration in `.changeset/config.json`. The default config is: + +```json +{ + "changelog": "@changesets/cli/changelog", + "commit": false, + "fixed": [], + "linked": [], + "access": "restricted", + "baseBranch": "main", + "changedFilePatterns": ["**"], + "format": "auto", + "privatePackages": { "version": true, "tag": false }, + "updateInternalDependencies": "patch", + "ignore": [], + "bumpVersionsWithWorkspaceProtocolOnly": false +} +``` + +## changelog + +- **Type:** `false | string | [string, Record]` +- **Default:** `"@changesets/cli/changelog"` + +Set how the changelog for packages should be generated. The default changelog generator is `@changesets/cli/changelog` (an alias to `@changesets/changelog-git`) which adds related commit links to each changeset entry in the changelog. If it is set to `false`, no changelogs will be generated. + +You can also specify a custom changelog generator by providing a string or a tuple with the module path and options. The module can be an npm package or a relative file path. Check out the [changelog generators](../advanced/modifying-changelog-format.md) guide to learn how to write your own changelog generator. + +If a tuple (`[string, Record]`) is set, you can pass options in the second item of the tuple to configure the changelog generator. For example, if you are using `@changesets/changelog-github`, you can pass the `repo` and `disableThanks` options like this: + +```json +{ + "changelog": [ + "@changesets/changelog-github", + { "repo": "owner/repo", "disableThanks": true } + ] +} +``` + +Consult the documentation for the changelog generator you're using for more information on the options you can pass to it. + +## commit + +- **Type:** `boolean | string | [string, Record]` +- **Default:** `false` + +Enable this option to automatically commit the changes when running the `changeset add` and `changeset version` commands. If set to `true`, the default commit message generator (`["@changesets/cli/commit", { "skipCI": "version" }]`) will be used. + +This option works similarly to the [`changelog`](#changelog) option. Check out the [commit generators](../advanced/modifying-changelog-format.md) guide to learn how to write your own commit message generator. + + + +## fixed + +- **Type:** `string[][]` +- **Default:** `[]` +- **Related:** [Fixed Packages](../advanced/fixed-packages.md) +- **Note:** Only applicable in monorepos. + +Declare that packages should be version-bumped and published together. Supports [picomatch patterns](https://github.com/micromatch/picomatch) to match packages. + +For example, if you have `pkg-a@1.0.0` and `pkg-b@1.0.0`, when one gets bumped to `1.1.0`, the other is also bumped to `1.1.0` regardless if it has any change or not. To achieve this, you can configure like so: + +```json +{ + "fixed": [["pkg-a", "pkg-b"]] +} +``` + +Learn more about the implementation and implications in the [Fixed Packages](../advanced/fixed-packages.md) guide. + +## linked + +- **Type:** `string[][]` +- **Default:** `[]` +- **Related:** [Linked Packages](../advanced/linked-packages.md) +- **Note:** Only applicable in monorepos. + +Declare that packages should "share" a version together. Supports [picomatch patterns](https://github.com/micromatch/picomatch) to match packages. + +For example, if you have `pkg-a@1.0.0` and `pkg-b@1.1.0`, if `pkg-a` is minor-bumped, it uses the shared highest version in the group which is `1.1.0` and bumps to `1.2.0`. `pkg-b` will not be explicitly bumped. To achieve this, you can configure like so: + +```json +{ + "linked": [["pkg-a", "pkg-b"]] +} +``` + +Learn more about the implementation and implications in the [Linked Packages](../advanced/linked-packages.md) guide. + +::: warning This does not do what some other tools do + +If you want to ensure the packages are always published with the same version, use the [`fixed`](#fixed) option instead. + +::: + +## access + +- **Type:** `"restricted" | "public"` +- **Default:** `"restricted"` + +Sets how packages are published. If `access: "restricted"`, packages will be published as private, requiring log in to an npm account with access to install. If `access: "public"`, the packages will be made available on the public registry. + +By default, npm publishes scoped npm packages as `restricted`, so to ensure you do not accidentally publish code publicly, we default to `restricted`. For most cases you will want to set this to `public`. + +This can be overridden in specific packages by setting `"publishConfig": { "access": "..." }` in a package's `package.json`. + +If you want to prevent a package from being published to npm, set `"private": true` in that package's `package.json` + +## baseBranch + +- **Type:** `string` +- **Default:** `"main"` + +The branch to which Changesets will make comparisons to detect what has changed since the last commit of the base branch. This should generally be set to the default branch you merge changes into, e.g. `main` or `master`. + +Commands that use this information accept a `--since` option which can be used to override this. + +Locally, make sure the base branch exists and is up to date so Changesets can make accurate comparisons. + +## changedFilePatterns + +- **Type:** `string[]` +- **Default:** `["**"]` + +The [picomatch patterns](https://github.com/micromatch/picomatch) for changed files that should mark a package as changed. Useful to fine-tune what counts as a change (e.g. only source files, ignoring test files, etc). + +Example: + +```json +{ + "changedFilePatterns": ["src/**", "lib/**"] +} +``` + +## format + +- **Type:** `"auto" | "prettier" | "prettier" | "oxfmt" | "deno" | "dprint" | false` +- **Default:** `"auto"` + +The code formatter to use for generated changeset files and changelogs. If set to `false`, no formatting will be applied. + +In `"auto"` mode, Changesets uses [@changesets/format](https://github.com/changesets/format) to automatically detect the preferred code formatter used in the project and applies it to generated files. You can explicitly set the formatter if you have multiple formatters set up in your project. + +## privatePackages + +- **Type:** `{ version?: boolean; tag?: boolean } | false` + +Controls how private packages should be versioned and tagged. By default, Changesets will update the version for private packages but will not create a tag. + +### privatePackages.version + +- **Type:** `boolean` +- **Default:** `true` + +Whether to update the version of private packages when running `changeset version`. + +### privatePackages.tag + +- **Type:** `boolean` +- **Default:** `false` + +Whether to create a tag for private packages when running `changeset publish`. + +## updateInternalDependencies + +- **Type:** `"patch" | "minor"` +- **Default:** `"patch"` +- **Note:** Only applicable in monorepos. + +Controls how internal dependencies should be updated when the depended-upon package is updated. To make this more understandable, here is an example: + +Say we have two packages, one depending on the other: + +``` +pkg-a @ version 1.0.0 +pkg-b @ version 1.0.0 + depends on pkg-a at range ^1.0.0 +``` + +And we are publishing a patch of both `pkg-a` and `pkg-b`. If the option is set to `patch`, we will update the pkg-a dependency range so we will now have: + +``` +pkg-a @ version 1.0.1 +pkg-b @ version 1.0.1 + depends on pkg-a at range ^1.0.1 <-- updated +``` + +However, if the option is set to `minor`, the range will only be updated when there is a minor change: + +``` +pkg-a @ version 1.0.1 +pkg-b @ version 1.0.1 + depends on pkg-a at range ^1.0.0 <-- not updated +``` + +Using `minor` allows consumers to more actively control their own deduplication of packages, and will allow them to install fewer versions if you have many interconnected packages. Using `patch` will mean consumers will more often be using updated code, but may cause problems with deduplication. + +Changesets will always update the dependency range if it would leave the old semver range. + +::: warning + +The dependency range will only be updated if the package (that contains the dependency) is being released. For example, if `pkg-b` depends on `pkg-a`, and only `pkg-a` is released, the dependency range in `pkg-b` will not be updated. + +::: + +## ignore + +- **Type:** `string[]` +- **Default:** `[]` +- **Note:** Only applicable in monorepos. + +Specify the packages that will not be published, even if they are referenced in changesets. Instead, those changesets will be skipped until they are removed from this array. Supports [picomatch patterns](https://github.com/micromatch/picomatch) to match packages. + +::: warning For temporary use only + +This feature is designed for temporary use to allow changes to be merged without publishing them. If you want to stop a package from being published at all, set `"private": true` in its `package.json`. + +::: + +There are two caveats to this: + +1. If the package is mentioned in a changeset that also includes a package that is not ignored, publishing will fail. +2. If the package requires one of its dependencies to be updated as part of a publish, publishing will also fail. + +These restrictions exist to ensure your repository or published code do not end up in a broken state. + +## bumpVersionsWithWorkspaceProtocolOnly + +- **Type:** `boolean` +- **Default:** `false` +- **Note:** Only applicable in monorepos. + +Whether to only bump dependency ranges that use the `workspace:` protocol of packages that are part of the workspace. + +## snapshot + +- **Type:** `{ useCalculatedVersion?: boolean; prereleaseTemplate?: string }` + +Configure snapshot releases when using `changesets version --snapshot`. + +- `prereleaseTemplate`: Configure the suffix for the snapshot releases, using a template with placeholders. If not specified, it will default to `{tag}-{datetime}` (or `{datetime}` if the tag is empty). Available placeholders are `{tag}`, `{commit}`, `{timestamp}`, and `{datetime}`. Note that if you are using `--snapshot` with an empty tag name, you cannot use `{tag}` as a placeholder - this will result in an error. + +### snapshot.useCalculatedVersion + +- **Type:** `boolean` +- **Default:** `false` + +Snapshot version uses `0.0.0` as the base version, e.g. `0.0.0-tag-20211213000730`. Setting this to `true` will use the calculated version based on the changeset files. + +### snapshot.prereleaseTemplate + +- **Type:** `string` +- **Default:** `"{tag}-{datetime}"` (or `"{datetime}"` if the tag is empty) + +Configures the suffix for the snapshot release using a template with placeholders: + +- `{tag}` - the name of the snapshot tag, as specified in `--snapshot something` +- `{commit}` - the git commit SHA (40 characters) +- `{timestamp}` - the Unix timestamp of the time of the release, i.e. the value of `Date.now()` +- `{datetime}` - the date and time of the release, e.g. `20211213000730` (YYYYMMDDHHMMSS, 14 characters) + +::: warning + +If you are using `--snapshot` with empty tag name, you cannot use `{tag}` as a placeholder. This will result in an error. + +::: diff --git a/site/guide/basic/configuration.md b/site/guide/basic/configuration.md deleted file mode 100644 index ad06aa8f3..000000000 --- a/site/guide/basic/configuration.md +++ /dev/null @@ -1,271 +0,0 @@ -# Configuring Changesets - -Changesets has a minimal amount of configuration options. Mostly these are for when you need to change the default workflows. These are stored in `.changeset/config.json`. Our default config is: - -```json -{ - "changelog": "@changesets/cli/changelog", - "commit": false, - "fixed": [], - "linked": [], - "access": "restricted", - "baseBranch": "master", - "updateInternalDependencies": "patch", - "ignore": [], - "bumpVersionsWithWorkspaceProtocolOnly": false, - "changedFilePatterns": ["**"], - "prettier": true, - "privatePackages": { "version": true, "tag": false } -} -``` - -> [!NOTE] -> The `linked`, `fixed`, `updateInternalDependencies`, `bumpVersionsWithWorkspaceProtocolOnly`, and `ignore` options are only for behaviour in monorepos. - -## `commit` (`boolean`, or module path as a `string`, or a tuple like `[modulePath: string, options: any]`) - -This option is for setting if the `changeset add` command and the `changeset version` commands will also add and commit the changed files using git, and how the commit messages should be generated for them. - -By default, we do not commit the files, and leave it to the user to commit the files. If it is `true`, we use the default commit message generator (`["@changesets/cli/commit", { "skipCI": "version" }]`). Setting it to a string and options tuple specifies a path from where we will load the commit message generation functions. It expects to be a file that exports one or both of the following: - -``` -{ - getAddMessage, - getVersionMessage -} -``` - -If one of the methods is not present then we will not commit the files changed for that command. - -You would specify a custom commit message generator with: - -```json -{ - "commit": ["../scripts/commit.js", { "customOption": true }] -} -``` - -This is similar to how the [changelog generator functions work](#changelog-false-or-a-path). - -## `access` (`restricted` | `public`) - -This sets how packages are published - if `access: "restricted"`, packages will be published as private, requiring log in to an npm account with access to install. If `access: "public"`, the packages will be made available on the public registry. - -By default, npm publishes scoped npm packages as `restricted` - so to ensure you do not accidentally publish code publicly, we default to `restricted`. For most cases you will want to set this to `public`. - -This can be overridden in specific packages by setting the `access` in a package's `package.json`. - -If you want to prevent a package from being published to npm, set `private: true` in that package's `package.json` - -## `baseBranch` (git branch name) - -The branch to which changesets will make comparisons to detect what has changed since the last commit of the base branch. This should generally be set to the default branch you merge changes into, e.g. `main` or `master`. - -Commands that use this information accept a `--since` option which can be used to override this. - -Locally, make sure the base branch exists and is up to date so changesets can make accurate comparisons. - -## `ignore` (array of packages) - -This option allows you to specify some packages that will not be published, even if they are referenced in changesets. Instead, those changesets will be skipped until they are removed from this array. - -> [!IMPORTANT] -> THIS FEATURE IS DESIGNED FOR TEMPORARY USE TO ALLOW CHANGES TO BE MERGED WITHOUT PUBLISHING THEM - If you want to stop a package from being published at all, set `private: true` in its `package.json`. - -There are two caveats to this. - -1. If the package is mentioned in a changeset that also includes a package that is not ignored, publishing will fail. -2. If the package requires one of its dependencies to be updated as part of a publish. - -These restrictions exist to ensure your repository or published code do not end up in a broken state. For a more detailed intricacies of publishing, check out our guide on [problems publishing in monorepos](../advanced/publishing-in-monorepos.md). - -> [!TIP] -> You can also provide glob expressions to match the packages, according to the [picomatch](https://npmx.dev/picomatch) format. - -## `fixed` (array of arrays of package names) - -This option can be used to declare that packages should be version-bumped and published together. As an example, if you have a `@changesets/button` component and a `@changesets/theme` component and you want to make sure that when one gets bumped to `1.1.0`, the other is also bumped to `1.1.0` regardless if it has any change or not. To achieve this you would have the config: - -```json -{ - "fixed": [["@changesets/button", "@changesets/theme"]] -} -``` - -If you want to use this option, you should read the documentation on [fixed packages](../advanced/fixed-packages.md) to fully understand the implementation and implications. - -## `linked` (array of arrays of package names) - -This option can be used to declare that packages should 'share' a version, instead of being versioned completely independently. As an example, if you have a `@changesets/button` component and a `@changesets/theme` component and you want to make sure that when one gets bumped to `2.0.0`, the other is also bumped to `2.0.0`. To achieve this you would have the config: - -```json -{ - "linked": [["@changesets/button", "@changesets/theme"]] -} -``` - -If you want to use this option, you should read the documentation on [linked packages](../advanced/linked-packages.md) to fully understand the implementation and implications. - -> [!WARNING] -> This does not do what some other tools do, which is make sure when any package is published, all other packages are also published with the same version. - -## `updateInternalDependencies` - -This option sets whether, when a package that is being depended upon changes, whether you should update what version it depends on. To make this more understandable, here is an example: - -Say we have two packages, one depending on the other: - -``` -pkg-a @ version 1.0.0 -pkg-b @ version 1.0.0 - depends on pkg-a at range `^1.0.0 -``` - -Say we are publishing a patch of both `pkg-a` and `pkg-b` - this flag is for determining whether we update how `pkg-b` depends on `pkg-a`. - -If the option is set to `patch`, we will update the dependency so we will now have: - -``` -pkg-a @ version 1.0.1 -pkg-b @ version 1.0.1 - depends on pkg-a at range `^1.0.1 -``` - -If however the option is set to `minor`, what it depends on will only be updated when there is a minor change, so the state would be: - -``` -pkg-a @ version 1.0.1 -pkg-b @ version 1.0.1 - depends on pkg-a at range `^1.0.0 -``` - -Using `minor` allows consumers to more actively control their own deduplication of packages, and will allow them to install fewer versions if you have many interconnected packages. Using `patch` will mean consumers will more often be using more updated code, but may cause problems with deduplication. - -Changesets will always update the dependency if it would leave the old semver range. - -> [!WARNING] -> This is only applied for packages which are already released in the current release. If A depends on B and we only release B then A won't be bumped. - -## `changelog` (false or a path) - -This option is for setting how the changelog for packages should be generated. If it is `false`, no changelogs will be generated. Setting it to a string specifies a path from where we will load the changelog generation functions. It expects a file that exports the following: - -``` -{ - getReleaseLine, - getDependencyReleaseLine -} -``` - -As well as the default one, you can use `@changesets/changelog-git`, which adds links to commits into changelogs, or `@changesets/changelog-github`, which requires github authentication, and includes a thankyou message to the person who added the changeset as well as a link to the relevant PR. - -You would specify our github changelog generator with: - -```json -{ - "changelog": ["@changesets/changelog-github", { "repo": "/" }] -} -``` - -If you want to disable thank you messages, add `"disableThanks": true` to the options. - -For more details on these functions and information on how to write your own see [changelog-functions](../advanced/modifying-changelog-format.md) - -## `bumpVersionsWithWorkspaceProtocolOnly` (optional boolean) - -Default value: `false` - -Determines whether Changesets should only bump dependency ranges that use workspace protocol of packages that are part of the workspace. - -## `snapshot` (object or undefined) - -Default value: `undefined` - -### `useCalculatedVersion` (optional boolean) - -Default value: `false` - -When `changesets version --snapshot` is used, the default behavior is to use `0.0.0` as the base version for the snapshot release. - -Setting `useCalculatedVersion: true` will change the default behavior and will use the calculated version, based on the changeset files. - -### `prereleaseTemplate` (optional string) - -Default value: `undefined` (see note below) - -Configures the suffix for the snapshot releases, using a template with placeholders. - -**Available placeholders:** - -You can use the following placeholders for customizing the snapshot release version: - -- `{tag}` - the name of the snapshot tag, as specified in `--snapshot something` -- `{commit}` - the Git commit ID -- `{timestamp}` - Unix timestamp of the time of the release -- `{datetime}` - date and time of the release (14 characters, for example, `20211213000730`) - -> [!WARNING] -> If you are using `--snapshot` with empty tag name, you cannot use `{tag}` as placeholder - this will result in error. - -**Default behavior** - -If you are not specifying `prereleaseTemplate`, the default behavior will fall back to using the following template: `{tag}-{datetime}`, and in cases where the tag is empty (`--snapshot` with no tag name), it will use `{datetime}` only. - -## `prettier` (optional boolean) - -This option configures whether Changesets will format its output using Prettier. When set to `false`, Changesets will skip formatting with Prettier. - -Default value: `true` - -```json -{ - "prettier": false -} -``` - -## `privatePackages` (object or false) - -This option is for setting how private packages should be handled. By default, Changesets will update the changelog for private packages and update their version, but will not create a tag. You can configure this option to change the default behavior. - -### `version` (optional boolean) - -Default value: `true` - -When `version` is set to `true`, Changesets will update the version for private packages. If set to `false`, Changesets will not update the version for private packages. - -### `tag` (optional boolean) - -Default value: `false` - -When `tag` is set to `true`, Changesets will create a tag for private packages. If set to `false`, Changesets will not create a tag for private packages. - -### Example - -```json -{ - "privatePackages": { - "version": true, - "tag": false - } -} -``` - -## `changedFilePatterns` (array of strings) - -Glob patterns for changed files that should mark a package as changed. Useful to fine-tune what counts as a change (e.g. only source files, ignoring test files, etc). - -Default value: - -```json -{ - "changedFilePatterns": ["**"] -} -``` - -Example: - -```json -{ - "changedFilePatterns": ["src/**", "lib/**"] -} -``` From addc9413e779fd671d8a431579b0708dc9c2c538 Mon Sep 17 00:00:00 2001 From: bluwy Date: Thu, 21 May 2026 11:19:47 +0800 Subject: [PATCH 24/80] Improve getting-started --- site/faq.md | 4 +- site/guide/introduction/getting-started.md | 79 ++++++++++++++++++---- site/guide/introduction/origins.md | 2 +- 3 files changed, 71 insertions(+), 14 deletions(-) diff --git a/site/faq.md b/site/faq.md index dd2de03c8..04ac464cf 100644 --- a/site/faq.md +++ b/site/faq.md @@ -4,7 +4,9 @@ Check the [guide](./guide/introduction/getting-started.md) for more detailed exp ## What is a changeset? -A changeset is a Markdown file that describes a change, and includes YAML frontmatter that describes the affected packages with the respective [semver](https://semver.org) bump types. They typically look like this: +A changeset is a Markdown file with YAML frontmatter. The contents of the Markdown is the change summary which will be written to the changelog and the YAML frontmatter describes the packages that have changed and their respective [semver](https://semver.org) bump types. + +They typically look like this: ```md --- diff --git a/site/guide/introduction/getting-started.md b/site/guide/introduction/getting-started.md index 174388119..7da4c3064 100644 --- a/site/guide/introduction/getting-started.md +++ b/site/guide/introduction/getting-started.md @@ -4,28 +4,39 @@ Changesets has several meanings that are sometimes used interchangeably: -1. It is a tool to manage package versions and changelog generation in a project. It is designed to work in [monorepos](https://monorepo.tools) as well as single package repos. +1. It is a tool to manage package versions and changelog generation in a project, designed to work in [monorepos](https://monorepo.tools) as well as single package repos. -2. It is also a workflow that allows contributors to describe what their changes are and how they should be released. +2. It is also [a workflow](#usage) that allows contributors to describe what their changes are and how they should be released. -3. A change description is also known as a "changeset". Typically represented as markdown file, it records the affected packages, the type of change following [semver](https://semver.org), and the change summary to be added to the changelog. +3. It also represents a group of [changeset files](#what-is-a-changeset), which are Markdown files that each describe a change. -
+::: tip New to Changesets? +If you are contributing to a project that uses Changesets, check out the [frequently asked questions](../../faq.md) for a quick introduction to working with changesets. +::: + +## What is a changeset? -The Changesets development loop looks like this: +A changeset is a Markdown file with YAML frontmatter. The contents of the Markdown is the change summary which will be written to the changelog and the YAML frontmatter describes the packages that have changed and their respective [semver](https://semver.org) bump types. -1. When making a change, e.g. via a git commit or a PR, a changeset is added alongside. -2. When a release is ready, the version command is run which consumes all the changesets and updates the package versions and changelogs. -3. Then, the publish command is run to publish the new versions of packages. +They typically look like this: -The last two steps can be [automated in CI](../basic/automating-changesets.md). +```md +--- +"pkg-a": minor +"pkg-b": patch +--- + +Summary of the change +``` ## Setting Up +Install the Changesets CLI: + ::: code-group ```bash [npm] -$ npm install --save-dev @changesets/cli +$ npm install -D @changesets/cli ``` ```bash [pnpm] @@ -38,7 +49,7 @@ $ yarn add -D @changesets/cli ::: -Next, run `init` to set up the `.changeset` folder in your project: +And run `init` to set up the `.changeset` folder in your project: ::: code-group @@ -56,7 +67,11 @@ $ yarn changeset init ::: -Now, whenever you make a change, you can create a changeset through the CLI: +Your project is now using Changesets! + +## Usage + +Whenever you make a change, e.g. via a git commit or a PR, create a changeset alongside with the CLI: ::: code-group @@ -79,3 +94,43 @@ $ yarn changeset Since a changeset describes how a change should be released, changes that don't require a release do not need a changeset. As such, we **do not recommend** blocking contributions in the absence of a changeset. ::: + +Once you have accumulated some changesets and are ready to release, you can run the `version` command to update the package versions and changelogs: + +::: code-group + +```bash [npm] +$ npx @changesets/cli version +``` + +```bash [pnpm] +$ pnpm changeset version +``` + +```bash [yarn] +$ yarn changeset version +``` + +::: + +Then, run the `publish` command to publish the new versions of the packages: + +::: code-group + +```bash [npm] +$ npx @changesets/cli publish +``` + +```bash [pnpm] +$ pnpm changeset publish +``` + +```bash [yarn] +$ yarn changeset publish +``` + +::: + +And you have released your changes! When you make more changes again, repeat the process to continue releasing new versions of your packages. + +You can also [automate the `version` and `publish` steps](../basic/automating-changesets.md) in CI so that releasing is as simple as merging a PR. diff --git a/site/guide/introduction/origins.md b/site/guide/introduction/origins.md index 39bbac0a0..8d1932244 100644 --- a/site/guide/introduction/origins.md +++ b/site/guide/introduction/origins.md @@ -29,7 +29,7 @@ As storing this information directly in git is problematic, we store it in the f ## The Result -A changeset is a Markdown file with YAML frontmatter. The contents of the Markdown is the change summary which will be written to the changelog and the YAML frontmatter describes the packages have changed and their respective semver bump types: +A changeset is a Markdown file with YAML frontmatter. The contents of the Markdown is the change summary which will be written to the changelog and the YAML frontmatter describes the packages that have changed and their respective semver bump types: ```md --- From f4b2e0441959046a13555ad3c5ba2b12e9fd25a9 Mon Sep 17 00:00:00 2001 From: bluwy Date: Thu, 21 May 2026 15:14:47 +0800 Subject: [PATCH 25/80] Sync code groups --- eslint.config.mjs | 6 ++ site/.vitepress/theme/index.ts | 9 ++- site/.vitepress/theme/sync-code-groups.ts | 68 +++++++++++++++++++++++ 3 files changed, 82 insertions(+), 1 deletion(-) create mode 100644 site/.vitepress/theme/sync-code-groups.ts diff --git a/eslint.config.mjs b/eslint.config.mjs index 6ee5a900d..2e4d8f9cc 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -86,6 +86,12 @@ export default defineConfig( "import-lite/no-mutable-exports": "error", }, }, + { + files: ["site/.vitepress/theme/**"], + rules: { + "n/no-unsupported-features/node-builtins": "off", + }, + }, { files: [ "**/index.ts", // to be removed in next release (v4) when we are dropping default export diff --git a/site/.vitepress/theme/index.ts b/site/.vitepress/theme/index.ts index 2888ebae4..6d0b8638f 100644 --- a/site/.vitepress/theme/index.ts +++ b/site/.vitepress/theme/index.ts @@ -1,5 +1,12 @@ +import type { Theme } from "vitepress"; import DefaultTheme from "vitepress/theme"; import "./custom.css"; import "virtual:group-icons.css"; +import { syncCodeGroups } from "./sync-code-groups.ts"; -export default DefaultTheme; +export default { + extends: DefaultTheme, + enhanceApp() { + syncCodeGroups(); + }, +} satisfies Theme; diff --git a/site/.vitepress/theme/sync-code-groups.ts b/site/.vitepress/theme/sync-code-groups.ts new file mode 100644 index 000000000..f15e0ac5b --- /dev/null +++ b/site/.vitepress/theme/sync-code-groups.ts @@ -0,0 +1,68 @@ +const seenCodeGroups = new WeakSet(); +const syncEventName = "vitepress-sync-code-groups:tab-change"; + +export function syncCodeGroups() { + if (typeof document === "undefined") return; + + const observer = new MutationObserver(() => { + for (const group of document.querySelectorAll(".vp-code-group")) { + if (seenCodeGroups.has(group)) continue; + seenCodeGroups.add(group); + + const labels = group.querySelectorAll(".tabs > label"); + const key = getKeyFromLabels(labels); + + const update = () => { + const selected = localStorage.getItem(key); + if (!selected) return; + + // NOTE: Do not click the label as otherwise VitePress will scroll to it. + // We manually implement the active state here. + const i = [...labels].findIndex((l) => l.dataset.title === selected); + if (i < 0) return localStorage.removeItem(key); + + const blocks = group.querySelector(".blocks"); + if (!blocks) return; + + const current = [...blocks.children].find((c) => + c.classList.contains("active"), + ); + if (!current) return; + + const next = blocks.children[i]; + if (!next || current === next) return; + + current.classList.remove("active"); + next.classList.add("active"); + (labels[i].control as HTMLInputElement).checked = true; + }; + + // Update on page load + update(); + + // Update on tab change in other tabs + document.addEventListener(syncEventName, (event: any) => { + if (event.detail.key === key) update(); + }); + + // When a tab is clicked, update localStorage and notify other tabs + for (const label of labels) { + label.addEventListener("click", () => { + localStorage.setItem(key, label.dataset.title!); + document.dispatchEvent( + new CustomEvent(syncEventName, { detail: { key } }), + ); + }); + } + } + }); + observer.observe(document, { childList: true, subtree: true }); +} + +function getKeyFromLabels(labels: NodeListOf) { + const id = [...labels] + .map((l) => l.dataset.title) + .sort() + .join("-"); + return `vitepress-sync-code-groups:${id}`; +} From 2ff1c10946168a8b4892957cfc669ea050c6a78a Mon Sep 17 00:00:00 2001 From: bluwy Date: Thu, 21 May 2026 16:22:06 +0800 Subject: [PATCH 26/80] Update cli --- site/guide/basic/cli.md | 228 ++++++++++++++++++++++------------------ 1 file changed, 126 insertions(+), 102 deletions(-) diff --git a/site/guide/basic/cli.md b/site/guide/basic/cli.md index 6dea0943f..be7300d87 100644 --- a/site/guide/basic/cli.md +++ b/site/guide/basic/cli.md @@ -1,165 +1,189 @@ -# Command line options +# Command Line Interface -The command line for changesets is the main way of interacting with it. There are 4 main commands. If you are looking for how we recommend you setup and manage changesets with the commands, check out our [intro to using changesets](../introduction/getting-started.md) +The Changesets CLI is the main way of interacting with changesets. It provides a set of commands that allow you to manage your changesets, version your packages, and publish them. -- `init` -- `add [--empty] [--open] [--since ] [--message ]` -- `version [--ignore, --snapshot]` -- `publish [--otp=code, --tag]` -- `status [--since=master --verbose --output=JSON_FILE.json]` -- `pre [exit|enter {tag}]` -- `tag` + -The most important commands are `add`, which is used by contributors to add information about their changes, `version` - which is responsible for using the changesets generated by `add` to update package versions and changelogs, and then `publish` which publishes changes to npm. +```bash +Usage: + $ changeset [command] [options] -## `init` - -``` -changeset init -``` - -This command sets up the `.changeset` folder. It generates a readme and a config file. The config file includes the default options and comments on what these options represent. You should run this command once when you are setting up changesets. - -## `add` - -``` -changeset add +Commands: + init Initialize a new changesets setup + add Add a new changeset (default) + version Version packages and create changelogs + publish Publish packages to npm and create git tags + status Show the changesets that currently exist + tag Create git tags for the current version of all packages + pre [tag] Enter or exit prerelease mode (tag required for enter) ``` -or just +## init -``` -changeset +```bash +Usage: + $ changeset init ``` -This is the main command people use to interact with the changesets. +This command sets up the `.changeset` folder. It generates a readme and a config file with the default options. You should run this command once when setting up Changesets. -This command will ask you a series of questions, first about what packages you want to release, then what semver bump type for each package, then it will ask for a summary of the entire changeset. The final step will show the changeset it will generate and confirm that you want to add it. +## add -Once confirmed, the changeset will be written as a Markdown file that contains the summary and YAML front matter which stores the packages that will be released and the semver bump types for them. +```bash +Usage: + $ changeset add + $ changeset -A changeset that major bumps `@changesets/cli` would look like this: +Options: + --empty Add an empty changeset + --open Open the changeset in the editor after creating it + --since Detect changed packages since the provided git ref + -m, --message Directly provide a message to the changeset +Examples: + $ changeset -m 'Description' + $ changeset --open --since main ``` ---- -"@changesets/cli": major ---- -A description of the major changes. -If you want to modify this file after it's generated, that's completely fine or if you want to write changeset files yourself, that's also fine. -``` +This is the main command to interact with the changesets. -- `--empty` - allows you to create an empty changeset if no packages are being bumped, usually only required if you have CI that blocks merges without a changeset. +It will ask you a series of questions, first about what packages you want to release, then what semver bump type for each package, then it will ask for a summary of the changes. The final step will show the changeset it will generate and confirm that you want to add it. -``` -changeset --empty -``` +Once confirmed, the changeset will be written in the `.changeset` folder. If the [`commit`](./configuration-file.md#commit) option is enabled, the changeset will be automatically committed to git. -A changeset created with the empty flag would look like this: +::: info Empty changesets +If you have [CI that blocks merges](../basic/automating-changesets.md#blocking) without a changeset, pass `--empty` to create an empty changeset. +::: -``` ---- ---- -``` +::: info Changing base branch +When prompting for packages to release, Changesets will detect and suggest the changed packages since the last commit on [`baseBranch`](./configuration-file.md#basebranch). If you want to use a different base branch, tag, or git ref, you can change it with the `--since` option. -If you set the commit option in the config, the command will add the updated changeset files and then commit them. +```bash +$ changeset --since next +``` -- `--open` - opens the created changeset in an external editor -- `--message` (or `-m`) - provides the changeset summary from the command line instead of prompting for it. +::: -- `--since` - uses the provided branch, tag, or git ref (such as `main` or a git commit hash) to detect which packages have changed when populating the list of changed packages in the CLI. This is useful in gitflow workflows where you have multiple target branches and `baseBranch` in the config doesn't cover all use cases. If not provided, the command falls back to the `baseBranch` value in your `.changeset/config.json`. +## version -``` -changeset add --since=develop -``` +```bash +Usage: + $ changeset version -## version +Options: + --ignore Packages to ignore + --snapshot [name] Create a snapshot prerelease + --snapshot-prerelease-template