Skip to content

Commit e2023b0

Browse 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.
1 parent a4e6e1c commit e2023b0

80 files changed

Lines changed: 234 additions & 214 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -197,7 +197,7 @@ The directory listings below are the canonical map of the repository. **Whenever
197197
- `lib/wasm/` — WebAssembly module support: the async path a build takes today,
198198
plus the two pieces neither path owns — `EnableWasmLoadingPlugin` and
199199
`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
201201
removes it, which is why it stands apart rather than joining `lib/wasm/`.
202202
- `lib/watch/` — Watch mode: the watching handles a compiler returns, and `WatchIgnorePlugin`.
203203
- `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.
302302
**A re-export is owed only to a webpack-5 package that imports the path unconditionally.**
303303
Read the importer's tarball, not its download count: a package whose `peerDependencies`
304304
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
306306
imports something webpack 5 deleted — or that probes for the path inside a `try` to detect
307307
webpack 4 gets an entry under `removed` with that reason instead, because a re-export
308308
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
415415

416416
**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.
417417

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+
418438
## Testing
419439

420440
For directory structure, naming, and how to run a single case, see [TESTING_DOCS.md](TESTING_DOCS.md).

‎codecov.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ ignore:
3535
- "**/*.runtime.js"
3636
- "schemas/**/*"
3737
- "examples/**/*"
38-
# TODO webpack 6 remove
38+
# TODO in the next major release: remove
3939
- "lib/template/ChunkTemplate.js"
4040
- "lib/template/MainTemplate.js"
4141
- "lib/template/ModuleTemplate.js"

‎lib/Chunk.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,6 @@
55

66
"use strict";
77

8-
// TODO remove in webpack 6
9-
// Some old plugins use `require("webpack/lib/Chunk")`, in webpack@6 developer should migrate to `compiler.webpack.Chunk`
8+
// TODO in the next major release: remove
9+
// Some old plugins use `require("webpack/lib/Chunk")`, in the next major release developer should migrate to `compiler.webpack.Chunk`
1010
module.exports = require("./graph/Chunk");

‎lib/Compilation.js‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -548,7 +548,7 @@ const EMPTY_ASSET_INFO = Object.freeze({});
548548

549549
const esmDependencyCategory = "esm";
550550

551-
// TODO webpack 6: remove
551+
// TODO in the next major release: remove
552552
const deprecatedNormalModuleLoaderHook = util.deprecate(
553553
/**
554554
* Handles the callback logic for this hook.
@@ -561,7 +561,7 @@ const deprecatedNormalModuleLoaderHook = util.deprecate(
561561
"DEP_WEBPACK_COMPILATION_NORMAL_MODULE_LOADER_HOOK"
562562
);
563563

564-
// TODO webpack 6: remove
564+
// TODO in the next major release: remove
565565
/**
566566
* Define removed module templates.
567567
* @param {ModuleTemplates | undefined} moduleTemplates module templates
@@ -1100,7 +1100,7 @@ BREAKING CHANGE: Asset processing hooks in Compilation has been merged into a si
11001100
shouldGenerateChunkAssets: new SyncBailHook([]),
11011101
/** @type {SyncHook<[]>} */
11021102
beforeChunkAssets: new SyncHook([]),
1103-
// TODO webpack 6 remove
1103+
// TODO in the next major release: remove
11041104
/** @deprecated */
11051105
additionalChunkAssets:
11061106
/** @type {FakeHook<Pick<AsyncSeriesHook<[Chunks]>, "tap" | "tapAsync" | "tapPromise" | "name">>} */
@@ -1113,7 +1113,7 @@ BREAKING CHANGE: Asset processing hooks in Compilation has been merged into a si
11131113
)
11141114
),
11151115

1116-
// TODO webpack 6 deprecate
1116+
// TODO in the next major release: deprecate
11171117
/** @deprecated */
11181118
additionalAssets:
11191119
/** @type {FakeHook<Pick<AsyncSeriesHook<[]>, "tap" | "tapAsync" | "tapPromise" | "name">>} */
@@ -1124,7 +1124,7 @@ BREAKING CHANGE: Asset processing hooks in Compilation has been merged into a si
11241124
() => []
11251125
)
11261126
),
1127-
// TODO webpack 6 remove
1127+
// TODO in the next major release: remove
11281128
/** @deprecated */
11291129
optimizeChunkAssets:
11301130
/** @type {FakeHook<Pick<AsyncSeriesHook<[Chunks]>, "tap" | "tapAsync" | "tapPromise" | "name">>} */
@@ -1136,7 +1136,7 @@ BREAKING CHANGE: Asset processing hooks in Compilation has been merged into a si
11361136
"DEP_WEBPACK_COMPILATION_OPTIMIZE_CHUNK_ASSETS"
11371137
)
11381138
),
1139-
// TODO webpack 6 remove
1139+
// TODO in the next major release: remove
11401140
/** @deprecated */
11411141
afterOptimizeChunkAssets:
11421142
/** @type {FakeHook<Pick<AsyncSeriesHook<[Chunks]>, "tap" | "tapAsync" | "tapPromise" | "name">>} */
@@ -1148,10 +1148,10 @@ BREAKING CHANGE: Asset processing hooks in Compilation has been merged into a si
11481148
"DEP_WEBPACK_COMPILATION_AFTER_OPTIMIZE_CHUNK_ASSETS"
11491149
)
11501150
),
1151-
// TODO webpack 6 deprecate
1151+
// TODO in the next major release: deprecate
11521152
/** @deprecated */
11531153
optimizeAssets: processAssetsHook,
1154-
// TODO webpack 6 deprecate
1154+
// TODO in the next major release: deprecate
11551155
/** @deprecated */
11561156
afterOptimizeAssets: afterProcessAssetsHook,
11571157

@@ -1481,7 +1481,7 @@ BREAKING CHANGE: Asset processing hooks in Compilation has been merged into a si
14811481
this.buildDependencies = new LazySet();
14821482
/** @type {FileSystemDependencies} */
14831483
this.optionalBuildDependencies = new LazySet();
1484-
// TODO webpack 6 remove
1484+
// TODO in the next major release: remove
14851485
/**
14861486
* @deprecated
14871487
* @type {{ add: (item: string) => FileSystemDependencies }}
@@ -2012,7 +2012,7 @@ BREAKING CHANGE: Asset processing hooks in Compilation has been merged into a si
20122012
this.moduleGraph.setParents(dep, currentBlock, module, index);
20132013
if (
20142014
hasLazyBarrel &&
2015-
// TODO remove in webpack 6
2015+
// TODO in the next major release: remove
20162016
// It may be missing on custom dependency types not extending the base Dependency
20172017
"isLazy" in dep &&
20182018
dep.isLazy()
@@ -2346,7 +2346,7 @@ BREAKING CHANGE: Asset processing hooks in Compilation has been merged into a si
23462346
},
23472347
(err, result) => {
23482348
if (result) {
2349-
// TODO webpack 6: remove
2349+
// TODO in the next major release: remove
23502350
// For backward-compat
23512351
if (result.module === undefined && result instanceof Module) {
23522352
result = {
@@ -2782,7 +2782,7 @@ BREAKING CHANGE: Asset processing hooks in Compilation has been merged into a si
27822782
* @returns {void} returns
27832783
*/
27842784
addEntry(context, entry, optionsOrName, callback) {
2785-
// TODO webpack 6 remove
2785+
// TODO in the next major release: remove
27862786
const options =
27872787
typeof optionsOrName === "object"
27882788
? optionsOrName
@@ -4654,7 +4654,7 @@ Or do you want to use the entrypoints '${name}' and '${runtime}' independently o
46544654
.then(() => this._attachPendingRuntimeModules(callback), callback);
46554655
}
46564656

4657-
// TODO webpack 6 make chunkGraph argument non-optional
4657+
// TODO in the next major release: make chunkGraph argument non-optional
46584658
/**
46594659
* Adds runtime module.
46604660
* @param {Chunk} chunk target chunk
@@ -6270,7 +6270,7 @@ This prevents using hashes of each other and should be avoided.`);
62706270
reportErrors();
62716271

62726272
// for backward-compat temporary set the chunk graph
6273-
// TODO webpack 6
6273+
// TODO in the next major release: drop it
62746274
const old = this.chunkGraph;
62756275
this.chunkGraph = chunkGraph;
62766276
this.processRuntimeRequirements({
@@ -6601,7 +6601,7 @@ This prevents using hashes of each other and should be avoided.`);
66016601
// Hide from typescript
66026602
const compilationPrototype = Compilation.prototype;
66036603

6604-
// TODO webpack 6 remove
6604+
// TODO in the next major release: remove
66056605
Object.defineProperty(compilationPrototype, "modifyHash", {
66066606
writable: false,
66076607
enumerable: false,
@@ -6613,7 +6613,7 @@ Object.defineProperty(compilationPrototype, "modifyHash", {
66136613
}
66146614
});
66156615

6616-
// TODO webpack 6 remove
6616+
// TODO in the next major release: remove
66176617
Object.defineProperty(compilationPrototype, "cache", {
66186618
enumerable: false,
66196619
configurable: false,

‎lib/Compiler.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -493,7 +493,7 @@ class Compiler {
493493
);
494494
}
495495

496-
// TODO webpack 6: solve this in a better way
496+
// TODO in the next major release: solve this in a better way
497497
// e.g. move compilation specific info from Modules into ModuleGraph
498498
_cleanupLastCompilation() {
499499
if (this._lastCompilation !== undefined) {
@@ -524,7 +524,7 @@ class Compiler {
524524
}
525525
}
526526

527-
// TODO webpack 6: solve this in a better way
527+
// TODO in the next major release: solve this in a better way
528528
_cleanupLastNormalModuleFactory() {
529529
if (this._lastNormalModuleFactory !== undefined) {
530530
this._lastNormalModuleFactory.cleanupForCache();

‎lib/Dependency.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,6 @@
55

66
"use strict";
77

8-
// TODO remove in webpack 6
9-
// Some old plugins use `require("webpack/lib/Dependency")`, in webpack@6 developer should migrate to `compiler.webpack.Dependency`
8+
// TODO in the next major release: remove
9+
// Some old plugins use `require("webpack/lib/Dependency")`, in the next major release developer should migrate to `compiler.webpack.Dependency`
1010
module.exports = require("./graph/Dependency");

‎lib/DependencyTemplate.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
"use strict";
77

8-
// TODO remove in webpack 6
8+
// TODO in the next major release: remove
99
// Some old plugins use `require("webpack/lib/DependencyTemplate")`; it is not on
10-
// `compiler.webpack`, so in webpack@6 they should require `webpack/lib/template/DependencyTemplate`
10+
// `compiler.webpack`, so in the next major release they should require `webpack/lib/template/DependencyTemplate`
1111
module.exports = require("./template/DependencyTemplate");

‎lib/EntryPlugin.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,6 @@
55

66
"use strict";
77

8-
// TODO remove in webpack 6
9-
// Some old plugins use `require("webpack/lib/EntryPlugin")`, in webpack@6 developer should migrate to `compiler.webpack.EntryPlugin`
8+
// TODO in the next major release: remove
9+
// Some old plugins use `require("webpack/lib/EntryPlugin")`, in the next major release developer should migrate to `compiler.webpack.EntryPlugin`
1010
module.exports = require("./entry/EntryPlugin");

‎lib/Entrypoint.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,6 @@
55

66
"use strict";
77

8-
// TODO remove in webpack 6
9-
// Some old plugins use `require("webpack/lib/Entrypoint")`, in webpack@6 developer should migrate to `compiler.webpack.Entrypoint`
8+
// TODO in the next major release: remove
9+
// Some old plugins use `require("webpack/lib/Entrypoint")`, in the next major release developer should migrate to `compiler.webpack.Entrypoint`
1010
module.exports = require("./graph/Entrypoint");

‎lib/ExternalsPlugin.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,6 @@
55

66
"use strict";
77

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`
1010
module.exports = require("./externals/ExternalsPlugin");

0 commit comments

Comments
 (0)