Skip to content

Commit c62debb

Browse files
anthonyshewanthonyshew
committed
WIP dbdaf
1 parent d331de2 commit c62debb

File tree

1 file changed

+31
-134
lines changed

1 file changed

+31
-134
lines changed

‎RELEASE.md‎

Lines changed: 31 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -74,14 +74,12 @@ Before triggering a release, ensure:
7474

7575
#### Version Storage
7676

77-
The single source of truth for the Turborepo version is **`version.txt`** at the repository root:
77+
The single source of truth for the Turborepo version is **`version.txt`** at the repository root. This file contains two lines:
7878

79-
```
80-
Line 1: Version number (e.g., 2.6.1)
81-
Line 2: NPM dist-tag (e.g., latest, canary)
82-
```
79+
- Line 1: Version number (e.g., 2.6.1)
80+
- Line 2: NPM dist-tag (e.g., latest, canary)
8381

84-
**Current version**: `2.6.1`
82+
See: `version.txt`
8583

8684
#### Version Calculation
8785

@@ -108,23 +106,12 @@ When a release is triggered, the `scripts/version.js` script:
108106

109107
#### Version Synchronization
110108

111-
Once the version is calculated, the `cli/Makefile` (target: `stage-release`) updates all package.json files:
112-
113-
```makefile
114-
# Updates all package.json versions to match TURBO_VERSION
115-
cd packages/turbo && pnpm version "$(TURBO_VERSION)" --allow-same-version
116-
cd packages/create-turbo && pnpm version "$(TURBO_VERSION)" --allow-same-version
117-
cd packages/turbo-codemod && pnpm version "$(TURBO_VERSION)" --allow-same-version
118-
cd packages/turbo-ignore && pnpm version "$(TURBO_VERSION)" --allow-same-version
119-
cd packages/turbo-workspaces && pnpm version "$(TURBO_VERSION)" --allow-same-version
120-
cd packages/turbo-gen && pnpm version "$(TURBO_VERSION)" --allow-same-version
121-
cd packages/eslint-plugin-turbo && pnpm version "$(TURBO_VERSION)" --allow-same-version
122-
cd packages/eslint-config-turbo && pnpm version "$(TURBO_VERSION)" --allow-same-version
123-
cd packages/turbo-types && pnpm version "$(TURBO_VERSION)" --allow-same-version
124-
```
109+
Once the version is calculated, the `cli/Makefile` (target: `stage-release`) updates all package.json files by running `pnpm version` for each package to match `TURBO_VERSION`.
125110

126111
Additionally, the `packages/turbo/bump-version.js` postversion hook updates the `optionalDependencies` in `packages/turbo/package.json` to reference the correct versions of platform-specific packages.
127112

113+
See: `cli/Makefile` (stage-release target) and `packages/turbo/bump-version.js`
114+
128115
---
129116

130117
### Release Workflow Stages
@@ -197,15 +184,9 @@ The release workflow consists of 6 sequential and parallel stages:
197184

198185
**Output**: `stage-branch` (e.g., `staging-2.6.2`)
199186

200-
**Safety Checks**:
187+
**Safety Checks**: The Makefile includes safety checks to verify no unpushed commits exist and that `version.txt` was properly updated before proceeding.
201188

202-
```bash
203-
# Fail if unpushed commits exist
204-
test "" = "`git cherry`" || (echo "Refusing to publish with unpushed commits" && false)
205-
206-
# Fail if version.txt wasn't updated
207-
test "" != "`git diff -- ../version.txt`" || (echo "Refusing to publish with unupdated version.txt" && false)
208-
```
189+
See: `cli/Makefile` (stage-release target)
209190

210191
#### Stage 2: Rust Smoke Test
211192

@@ -253,17 +234,9 @@ This runs TypeScript type checking and all Jest/Vitest tests for JavaScript pack
253234

254235
**Build Configuration**:
255236

256-
The Rust binaries are built using the `release-turborepo` profile defined in `Cargo.toml`:
237+
The Rust binaries are built using the `release-turborepo` profile (inherits from release profile with stripping enabled) and Link-time optimization (LTO) enabled via the `CARGO_PROFILE_RELEASE_LTO=true` environment variable.
257238

258-
```toml
259-
[profile.release-turborepo]
260-
inherits = "release"
261-
strip = true # Remove debug symbols for smaller binaries
262-
```
263-
264-
Additional build flags:
265-
266-
- `CARGO_PROFILE_RELEASE_LTO=true` - Link-time optimization for better performance and smaller size
239+
See: `Cargo.toml` (release-turborepo profile) and `.github/workflows/turborepo-release.yml`
267240

268241
**Build Steps**:
269242

@@ -292,21 +265,9 @@ This is the most complex stage with multiple sub-steps:
292265

293266
##### 5b. Build JavaScript Packages
294267

295-
Execute `make -C cli build`:
268+
Execute `make -C cli build` which runs `turbo build copy-schema` with filters for all JavaScript/TypeScript packages. This builds all TypeScript packages and copies the JSON schema to the appropriate locations.
296269

297-
```bash
298-
turbo build copy-schema \
299-
--filter=create-turbo \
300-
--filter=@turbo/codemod \
301-
--filter=turbo-ignore \
302-
--filter=@turbo/workspaces \
303-
--filter=@turbo/gen \
304-
--filter=eslint-plugin-turbo \
305-
--filter=eslint-config-turbo \
306-
--filter=@turbo/types
307-
```
308-
309-
This builds all TypeScript packages and copies the JSON schema to the appropriate locations.
270+
See: `cli/Makefile` (build target)
310271

311272
##### 5c. Pack and Publish Native Packages
312273

@@ -316,27 +277,16 @@ Execute `turbo release-native` which invokes the `@turbo/releaser` tool.
316277

317278
1. **Reads version and tag** from `version.txt`
318279
2. **For each platform** (6 total):
319-
- Generates a native package structure:
320-
- `package.json` with platform-specific metadata:
321-
```json
322-
{
323-
"name": "turbo-darwin-64",
324-
"version": "2.6.2",
325-
"os": ["darwin"],
326-
"cpu": ["x64"],
327-
"description": "The darwin-x64 binary for turbo",
328-
"license": "MIT",
329-
"repository": "https://github.com/vercel/turborepo",
330-
"preferUnplugged": true
331-
}
332-
```
333-
- Copies `LICENSE` and `README.md` from template
334-
- For Windows: includes a `bin/turbo` Node.js wrapper script (to work around npm `.exe` stripping)
280+
- Generates a native package structure with platform-specific metadata (name, os, cpu, etc.)
281+
- Copies `LICENSE` and `README.md` from template
282+
- For Windows: includes a `bin/turbo` Node.js wrapper script (to work around npm `.exe` stripping)
335283
- Copies the prebuilt binary from `cli/dist-<os>-<arch>/`
336284
- Makes the binary executable (`chmod +x` on Unix)
337285
- Creates a `.tar.gz` archive
338286
- Publishes to npm: `npm publish turbo-<os>-<arch>.tar.gz --tag <npm-tag>`
339287

288+
See: `packages/turbo-releaser/` for native package generation logic
289+
340290
**Published native packages**:
341291

342292
- `turbo-darwin-64`
@@ -350,26 +300,10 @@ Execute `turbo release-native` which invokes the `@turbo/releaser` tool.
350300

351301
Execute `make -C cli publish-turbo` which:
352302

353-
1. **Packs all packages** to tarballs:
303+
1. **Packs all packages** to tarballs using `pnpm pack`
304+
2. **Publishes in fixed order** to npm with the appropriate dist-tag (if not `--skip-publish`)
354305

355-
```bash
356-
cd packages/turbo && pnpm pack --pack-destination=../
357-
cd packages/create-turbo && pnpm pack --pack-destination=../
358-
# ... and so on for all 9 packages
359-
```
360-
361-
2. **Publishes in fixed order** (if not `--skip-publish`):
362-
```bash
363-
npm publish --tag $(TURBO_TAG) turbo-$(TURBO_VERSION).tgz
364-
npm publish --tag $(TURBO_TAG) create-turbo-$(TURBO_VERSION).tgz
365-
npm publish --tag $(TURBO_TAG) turbo-codemod-$(TURBO_VERSION).tgz
366-
npm publish --tag $(TURBO_TAG) turbo-ignore-$(TURBO_VERSION).tgz
367-
npm publish --tag $(TURBO_TAG) turbo-workspaces-$(TURBO_VERSION).tgz
368-
npm publish --tag $(TURBO_TAG) turbo-gen-$(TURBO_VERSION).tgz
369-
npm publish --tag $(TURBO_TAG) eslint-plugin-turbo-$(TURBO_VERSION).tgz
370-
npm publish --tag $(TURBO_TAG) eslint-config-turbo-$(TURBO_VERSION).tgz
371-
npm publish --tag $(TURBO_TAG) turbo-types-$(TURBO_VERSION).tgz
372-
```
306+
See: `cli/Makefile` (publish-turbo target)
373307

374308
**Why fixed order?**
375309

@@ -440,23 +374,12 @@ The `turbo` package is unique:
440374
- Falls back to x64 on ARM64 for macOS/Windows (Rosetta/emulation support)
441375
- Provides just-in-time installation if the platform package is missing
442376

443-
2. **Declares platform packages as optional dependencies** in `package.json`:
444-
445-
```json
446-
{
447-
"optionalDependencies": {
448-
"turbo-darwin-64": "2.6.2",
449-
"turbo-darwin-arm64": "2.6.2",
450-
"turbo-linux-64": "2.6.2",
451-
"turbo-linux-arm64": "2.6.2",
452-
"turbo-windows-64": "2.6.2",
453-
"turbo-windows-arm64": "2.6.2"
454-
}
455-
}
456-
```
377+
2. **Declares platform packages as optional dependencies** - all six platform-specific packages are listed as `optionalDependencies` in the package.json, allowing npm to install only the relevant one for the current platform.
457378

458379
3. **Entry point**: `packages/turbo/bin/turbo` (Node.js script)
459380

381+
See: `packages/turbo/package.json` and `packages/turbo/bin/turbo`
382+
460383
---
461384

462385
### Platform-Specific Binaries
@@ -467,42 +390,23 @@ When a user runs `turbo`, the `packages/turbo/bin/turbo` script:
467390

468391
1. **Checks `TURBO_BINARY_PATH`** environment variable (for local development)
469392
2. **Detects platform**: `process.platform` and `process.arch`
470-
3. **Maps to package name**:
471-
```javascript
472-
const PLATFORM_PACKAGE_MAP = {
473-
"darwin-x64": "turbo-darwin-64",
474-
"darwin-arm64": "turbo-darwin-arm64",
475-
"linux-x64": "turbo-linux-64",
476-
"linux-arm64": "turbo-linux-arm64",
477-
"win32-x64": "turbo-windows-64",
478-
"win32-arm64": "turbo-windows-arm64",
479-
};
480-
```
393+
3. **Maps to package name** using a platform-to-package mapping
481394
4. **Attempts to require the correct platform package**
482395
5. **Falls back** to x64 on ARM64 for macOS and Windows (Rosetta 2 / emulation support)
483396
6. **Just-in-time install**: If the package is missing, attempts `npm install` for that specific platform
484397
7. **Errors with diagnostics** if all attempts fail
485398

399+
See: `packages/turbo/bin/turbo` for the complete platform detection logic
400+
486401
#### Windows Special Handling
487402

488403
Windows has special considerations:
489404

490405
1. **Binary name**: `turbo.exe`
491406
2. **npm `.exe` stripping issue**: npm strips `.exe` files from the `bin/` directory
492-
3. **Solution**: Native Windows packages include a `bin/turbo` Node.js wrapper script that:
407+
3. **Solution**: Native Windows packages include a `bin/turbo` Node.js wrapper script that spawns `turbo.exe` and forwards all arguments and stdio
493408

494-
```javascript
495-
// bin/turbo (Windows native package)
496-
#!/usr/bin/env node
497-
const { spawn } = require("child_process");
498-
const path = require("path");
499-
500-
const binPath = path.resolve(__dirname, "../turbo.exe");
501-
const result = spawn(binPath, process.argv.slice(2), { stdio: "inherit" });
502-
result.on("exit", (code) => process.exit(code));
503-
```
504-
505-
4. This wrapper spawns `turbo.exe` and forwards all arguments and stdio
409+
See: `packages/turbo-releaser/` for the Windows wrapper generation
506410

507411
---
508412

@@ -644,16 +548,9 @@ Windows has special considerations:
644548

645549
#### Rust Build Profile
646550

647-
```toml
648-
# Cargo.toml
649-
[profile.release-turborepo]
650-
inherits = "release"
651-
strip = true # Remove debug symbols
652-
```
653-
654-
Additional flags set during build:
551+
The `release-turborepo` profile inherits from the release profile with debug symbol stripping enabled. Link-time optimization is enabled via the `CARGO_PROFILE_RELEASE_LTO=true` environment variable during the build.
655552

656-
- `CARGO_PROFILE_RELEASE_LTO=true` - Link-time optimization
553+
See: `Cargo.toml` (release-turborepo profile)
657554

658555
#### Workflow Inputs Reference
659556

0 commit comments

Comments
 (0)