You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit e2023b0
Browse filesBrowse the repository at this point in the historyBrowse files
chore: mark deferred work with one version-agnostic wording (#22238)
* chore: mark deferred work with one version-agnostic wording
The 153 markers deferring work to the next major were written a dozen
ways — `TODO webpack 6`, `TODO remove in webpack 6`, `TODO webpack6 - …`,
`TODO reconsider this for webpack 6` — so no grep found them all, and a
number goes stale the moment that major ships. They now read
`TODO in the next major release: <what to do>`, which names the next
breaking release whenever it is read, and AGENTS.md states the convention
and the one command that lists them.
* chore: carry the version-agnostic wording to what the sweep missed
The first pass matched `webpack 6` and `webpack6`, so it left every
`webpack@6` behind — three markers, the sixteen deep-path re-export
headers and the prose beside them — along with a `@deprecated` tag and two
JSDoc descriptions that named the release rather than marking it. One
marker also stated the back-compat behavior instead of the work, which is
what the convention asks for. AGENTS.md now says the prose beside a marker
takes the same phrase, and its search command covers `codecov.yml` too.
Copy file name to clipboardExpand all lines: AGENTS.md
+22-2Lines changed: 22 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -197,7 +197,7 @@ The directory listings below are the canonical map of the repository. **Whenever
197
197
-`lib/wasm/` — WebAssembly module support: the async path a build takes today,
198
198
plus the two pieces neither path owns — `EnableWasmLoadingPlugin` and
199
199
`wasmModuleFilename`.
200
-
-`lib/wasm-sync/` — The synchronous WebAssembly path, kept until webpack 6
200
+
-`lib/wasm-sync/` — The synchronous WebAssembly path, kept until the next major release
201
201
removes it, which is why it stands apart rather than joining `lib/wasm/`.
202
202
-`lib/watch/` — Watch mode: the watching handles a compiler returns, and `WatchIgnorePlugin`.
203
203
-`hot/` — Runtime code shipped to browsers for HMR (browser-side, not Node tooling).
@@ -302,7 +302,7 @@ path `removed` names rather than recording it as a request.
302
302
**A re-export is owed only to a webpack-5 package that imports the path unconditionally.**
303
303
Read the importer's tarball, not its download count: a package whose `peerDependencies`
304
304
or `dependencies` name webpack 5 and which requires the path at the top level gets a
305
-
`// TODO remove in webpack 6` re-export at the old path. One that is webpack 4 only — it
305
+
`// TODO in the next major release: remove` re-export at the old path. One that is webpack 4 only — it
306
306
imports something webpack 5 deleted — or that probes for the path inside a `try` to detect
307
307
webpack 4 gets an entry under `removed` with that reason instead, because a re-export
308
308
would send it down the wrong branch.
@@ -415,6 +415,26 @@ Each surviving line must carry what the code cannot: a hidden invariant, an orde
415
415
416
416
**The description above those tags is prose, so it is capped at two sentences.** Say what the function does when its name doesn't, plus the one constraint a caller needs. Moving an essay out of a `//` comment into a JSDoc description is the same essay indented differently, not a fix — an explanation of the algorithm, the history, or the alternatives considered belongs in neither. Prose about a documented symbol goes inside its JSDoc, never as a `//` comment stacked on top of the block or standing in for it.
417
417
418
+
### Marking work for the next major
419
+
420
+
> [!REQUIRED]
421
+
422
+
Work that has to wait for the next breaking release is marked with one wording, everywhere, in every file type:
423
+
424
+
```js
425
+
// TODO in the next major release: remove, `css-url` is the old spelling of `asset-url`
426
+
```
427
+
428
+
**Never name a version, in a marker or in the prose beside one.**`TODO webpack 6`, `TODO remove in webpack 6`, `TODO webpack6 - …`, `TODO webpack@6` and `TODO reconsider this for webpack 6` all meant the same thing, and none of them found the others — which is how one cleanup came to be written a dozen ways. A `@deprecated` tag or a description saying what the next major does goes stale the same way, so it takes the same phrase. A number also goes stale the moment that major ships: what was deferred to 6 and missed is deferred to 7, and the comment still says 6. The phrase names the next breaking release whenever it happens to be read.
429
+
430
+
**Always say what to do**, not merely that something is pending — a bare marker tells the branch doing the work nothing. The comment is a plain comment, so the [three-line limit](#code-comments) binds it too.
431
+
432
+
The whole list is then one command, which is the point of the wording:
433
+
434
+
```sh
435
+
grep -rn "TODO in the next major release" codecov.yml bin hot lib setup test tooling
436
+
```
437
+
418
438
## Testing
419
439
420
440
For directory structure, naming, and how to run a single case, see [TESTING_DOCS.md](TESTING_DOCS.md).
Copy file name to clipboardExpand all lines: lib/ExternalsPlugin.js
+2-2Lines changed: 2 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -5,6 +5,6 @@
5
5
6
6
"use strict";
7
7
8
-
// TODO remove in webpack 6
9
-
// Some old plugins use `require("webpack/lib/ExternalsPlugin")`, in webpack@6 developer should migrate to `compiler.webpack.ExternalsPlugin`
8
+
// TODO in the next major release: remove
9
+
// Some old plugins use `require("webpack/lib/ExternalsPlugin")`, in the next major release developer should migrate to `compiler.webpack.ExternalsPlugin`
0 commit comments