Skip to content

Commit 250a1c6

Browse files
mdjastrzebskimdjastrzebski
committed
docs: versioning scheme
docs: ver
1 parent cf82821 commit 250a1c6

3 files changed

Lines changed: 155 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ The project uses **Bun** for development scripts, but you can install it via npm
4747
- **Testing:** Unit tests are located in `src/__tests__/`. Tests use `jest` and `ts-jest`.
4848
- **Linting:** ESLint is used for static analysis.
4949
- **Git:** Commits seem to follow standard conventions (implied by `release-it`).
50+
- **Versioning:** See `docs/versioning.md` for the `1.x` compatibility-line policy for React / React Reconciler support.
5051

5152
## Directory Structure
5253

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ This library is used by [React Native Testing Library](https://github.com/callst
66

77
This library replaces the deprecated React Test Renderer. It uses [React Reconciler](https://github.com/facebook/react/tree/main/packages/react-reconciler) to build a custom renderer that operates on host elements by default, and provides escape hatches for complex use-cases. Most React Reconciler options are exposed through `RootOptions`.
88

9+
For release and compatibility policy, see [docs/versioning.md](./docs/versioning.md).
10+
911
## Installation
1012

1113
```bash

‎docs/versioning.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Versioning
2+
3+
This document defines the versioning policy for `test-renderer` (TR) starting with `1.x`.
4+
5+
## Goals
6+
7+
- Prevent peer dependency errors or warnings for incompatible React versions.
8+
- Let consumers adopt new React features as soon as their React version supports them.
9+
- Let a consumer package such as a testing library depend on `test-renderer` without forcing all users onto the newest React 19 minor.
10+
- Avoid vendoring `react-reconciler` unless it becomes necessary.
11+
12+
## Constraints
13+
14+
`test-renderer` depends on a single `react-reconciler` (RR) version line at a time.
15+
16+
Because `react-reconciler` has a React peer dependency, one published `test-renderer` package can only cleanly support a bounded range of React versions. Without vendoring `react-reconciler` or shipping separate package names, supporting every React 19 minor from a single `test-renderer@latest` release would require one of two bad options:
17+
18+
- allowing incorrect installs, or
19+
- weakening peer dependency ranges so much that package managers stop protecting users from incompatible combinations.
20+
21+
## Policy
22+
23+
For `test-renderer` 1.x, the version number has two meanings:
24+
25+
- `major` tracks TR API or behavior breaks, or a move to a new React major.
26+
- `minor` tracks the supported React 19 compatibility line.
27+
- `patch` tracks fixes and features that stay within the same compatibility line.
28+
29+
In practice, this means each `1.x` minor corresponds to a specific React / RR line.
30+
31+
## Compatibility Lines
32+
33+
### `1.0.x`
34+
35+
- `react-reconciler`: `~0.31.0`
36+
- `peerDependencies.react`: `>=19.0.0 <19.1.0`
37+
38+
### `1.1.x`
39+
40+
- `react-reconciler`: `~0.32.0`
41+
- `peerDependencies.react`: `>=19.1.0 <19.2.0`
42+
43+
### `1.2.x`
44+
45+
- `react-reconciler`: `~0.33.0`
46+
- `peerDependencies.react`: `>=19.2.0 <19.3.0`
47+
48+
## Release Rules
49+
50+
### Patch releases
51+
52+
Use patch releases for:
53+
54+
- bug fixes within the current React compatibility line
55+
- internal improvements that do not raise the minimum supported React minor
56+
- new TR features that work on the existing RR line
57+
58+
Example:
59+
60+
- `1.1.2` -> `1.1.3` for a bug fix that still supports React `19.1.x`
61+
62+
### Minor releases
63+
64+
Use minor releases for:
65+
66+
- adopting a newer `react-reconciler` line
67+
- raising the minimum supported React 19 minor
68+
- introducing features that require the newer React / RR line
69+
70+
Examples:
71+
72+
- `1.0.x` -> `1.1.x` when moving from RR `0.31` to `0.32`
73+
- `1.1.x` -> `1.2.x` when moving from RR `0.32` to `0.33`
74+
75+
Minor releases may be incompatible for consumers on older React minors. This is intentional. The peer dependency range should make that incompatibility explicit at install time.
76+
77+
### Major releases
78+
79+
Use major releases for:
80+
81+
- TR API or behavior changes that break existing consumers across compatibility lines
82+
- a move from React `19` support to React `20`
83+
84+
## Backporting
85+
86+
If a new TR feature or bug fix does not depend on a newer React / RR line, it should be backported to every maintained compatibility line.
87+
88+
Examples:
89+
90+
- a fix that works everywhere may ship as `1.0.5`, `1.1.4`, and `1.2.1`
91+
- a feature that requires React `19.2` should ship only in `1.2.x`
92+
93+
This lets users on older React minor versions keep using the latest compatible consumer package without peer dependency issues, as long as that package does not require a newer `test-renderer` line.
94+
95+
## Peer Dependency Guidance
96+
97+
`test-renderer` should use bounded React peer ranges per compatibility line.
98+
99+
Recommended ranges:
100+
101+
- `1.0.x`: `>=19.0.0 <19.1.0`
102+
- `1.1.x`: `>=19.1.0 <19.2.0`
103+
- `1.2.x`: `>=19.2.0 <19.3.0`
104+
105+
Avoid using a broad range such as `^19.0.0` for every line. Doing so would let users install a `test-renderer` version backed by an older `react-reconciler` line with a newer React version than that line was designed for.
106+
107+
## Consumer Package Strategy
108+
109+
A consumer package such as a testing library should depend on `test-renderer` as a regular dependency, not a peer dependency.
110+
111+
Recommended range:
112+
113+
```json
114+
{
115+
"dependencies": {
116+
"test-renderer": "^1.0.0 || ^1.1.0 || ^1.2.0"
117+
}
118+
}
119+
```
120+
121+
This lets package managers choose the highest compatible `test-renderer` line based on the app's installed React version.
122+
123+
To make this work well, the consumer package should either:
124+
125+
- rely only on TR APIs available across all supported `1.x` compatibility lines, or
126+
- use feature detection when integrating with newer TR capabilities
127+
128+
## Dist Tags
129+
130+
For direct `test-renderer` consumers, publish dist tags for each compatibility line:
131+
132+
- `latest` -> newest supported line, typically the highest React 19 line
133+
- `react19.0` -> latest `1.0.x`
134+
- `react19.1` -> latest `1.1.x`
135+
- `react19.2` -> latest `1.2.x`
136+
137+
This keeps `npm` install flows predictable for users who consume `test-renderer` directly.
138+
139+
## Summary
140+
141+
The recommended `test-renderer` 1.x scheme is:
142+
143+
- `1.0.x` for React `19.0`
144+
- `1.1.x` for React `19.1`
145+
- `1.2.x` for React `19.2`
146+
147+
With this scheme:
148+
149+
- install-time peer dependency checks remain useful
150+
- a consumer package can stay compatible with multiple React 19 lines
151+
- new React features can be exposed as soon as a new compatibility line is published
152+
- vendoring `react-reconciler` is not required

0 commit comments

Comments
 (0)