Skip to content

Commit 3505f14

Browse files
committed
feat(docs): add developer-friendly release notes for v4.0.0
Add comprehensive release notes for alpha.0 and beta.0 releases: - RELEASE_NOTES_v4.0.0-alpha.0.md - Infrastructure changes - RELEASE_NOTES_v4.0.0-beta.0.md - Features and migration guide Follows best practices from TypeScript, Next.js, and Vitest: - Concise, scannable format - Before/after code examples - Real-world context - Clear migration steps - Technical tone without sales pitch - PR references - Direct links to resources Also updates failFast() TypeScript type to only accept { enabled: false } since fail-fast is ON by default in v4 and the method only exists to disable it.
1 parent 73dde18 commit 3505f14

File tree

3 files changed

+521
-29
lines changed

3 files changed

+521
-29
lines changed

RELEASE_NOTES_v4.0.0-alpha.0.md

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# v4.0.0-alpha.0 (2025-10-27)
2+
3+
Infrastructure modernization release. All changes are breaking and relate to runtime environment and module system.
4+
5+
## Summary
6+
7+
- Node.js 20+ required (dropped 16.x and 18.x)
8+
- All packages migrated to dual CJS/ESM builds
9+
- Manual type augmentation configuration required
10+
- InversifyJS v7 upgrade
11+
- Migrated from Yarn to pnpm
12+
13+
---
14+
15+
## Breaking Changes
16+
17+
### Node.js Version
18+
19+
Minimum version increased to Node.js 20.x. (#803)
20+
21+
**Before**: Node.js 16.x, 18.x supported
22+
**After**: Node.js 20.x, 22.x, 24.x required
23+
24+
```bash
25+
# Migration
26+
node --version # Must be >= 20.0.0
27+
nvm install 20
28+
nvm use 20
29+
```
30+
31+
---
32+
33+
### Module System
34+
35+
All packages now output dual CJS/ESM builds to `dist/cjs/` and `dist/esm/`.
36+
37+
**Before**:
38+
```
39+
node_modules/@suites/unit/
40+
dist/
41+
index.js
42+
services/
43+
```
44+
45+
**After**:
46+
```
47+
node_modules/@suites/unit/
48+
dist/
49+
cjs/
50+
index.js
51+
services/
52+
esm/
53+
index.js
54+
services/
55+
```
56+
57+
**Impact**: Direct file imports must update paths (normal imports unchanged).
58+
59+
```typescript
60+
// Normal imports work unchanged
61+
import { TestBed } from '@suites/unit'; // ✓ Still works
62+
63+
// Direct imports need update
64+
import { something } from '@suites/unit/dist/services/builder'; // Old
65+
import { something } from '@suites/unit/dist/cjs/services/builder'; // New
66+
```
67+
68+
**Affected packages**: All 10 packages
69+
**Commits**: Multiple commits, one per package
70+
71+
---
72+
73+
### Type Augmentation
74+
75+
Postinstall scripts removed. Manual configuration required.
76+
77+
**Before**: Types automatically injected via postinstall scripts
78+
**After**: Create `global.d.ts` manually
79+
80+
**Migration**:
81+
82+
1. Create `global.d.ts` in project root:
83+
```typescript
84+
/// <reference types="@suites/doubles.jest/unit" />
85+
/// <reference types="@suites/di.nestjs/types" />
86+
```
87+
88+
2. Add to `tsconfig.json`:
89+
```json
90+
{
91+
"include": ["src", "global.d.ts"]
92+
}
93+
```
94+
95+
**Affected packages**:
96+
- `@suites/doubles.jest`
97+
- `@suites/doubles.vitest`
98+
- `@suites/doubles.sinon`
99+
- `@suites/di.inversify`
100+
- `@suites/di.nestjs`
101+
102+
**Why**: Postinstall scripts caused CI/CD issues and violated npm best practices.
103+
104+
---
105+
106+
### InversifyJS v7
107+
108+
`@suites/di.inversify` now requires InversifyJS v7.x. (#884)
109+
110+
```bash
111+
npm install inversify@^7.0.0 reflect-metadata@^0.2.2
112+
```
113+
114+
**What changed**: Uses InversifyJS v7 metadata API
115+
116+
---
117+
118+
## Improvements
119+
120+
### Package Manager
121+
- Migrated from Yarn to pnpm 10.14.0 (#799)
122+
- Faster installs, better workspace support
123+
124+
### Dependencies
125+
- Removed lodash.isequal, using Node.js `util.isDeepStrictEqual()`
126+
- Lighter dependency footprint
127+
128+
### License
129+
- Changed from MIT to Apache-2.0
130+
131+
---
132+
133+
## Bug Fixes
134+
135+
- Fixed missing `@suites/types.doubles` dependency in core (#806)
136+
- Upgraded ts-mocha for Node 22/24 compatibility
137+
138+
---
139+
140+
## Documentation
141+
142+
Added comprehensive JSDoc to:
143+
- `@suites/unit` - TestBed API
144+
- `@suites/core.unit` - Core implementation
145+
- `@suites/doubles.jest` - Jest adapter
146+
- `@suites/doubles.vitest` - Vitest adapter
147+
- `@suites/doubles.sinon` - Sinon adapter
148+
- All type packages
149+
150+
---
151+
152+
## Migration Checklist
153+
154+
- [ ] Upgrade Node.js to 20+
155+
- [ ] Install alpha: `npm install @suites/[email protected]`
156+
- [ ] Create `global.d.ts` with type references
157+
- [ ] Add `global.d.ts` to `tsconfig.json` include array
158+
- [ ] If using Inversify: `npm install inversify@^7.0.0`
159+
- [ ] Run tests
160+
- [ ] Update CI/CD Node.js version
161+
162+
---
163+
164+
## Installation
165+
166+
```bash
167+
npm install @suites/[email protected]
168+
```
169+
170+
---
171+
172+
**Full Changelog**: https://github.com/suites-dev/suites/compare/v3.0.2...v4.0.0-alpha.0

0 commit comments

Comments
 (0)