Docs: Add migration guide for QUnit.config.countStepsAsOne

docs/api/assert/expect.md

@@ -28,6 +28,52 @@ It is recommended to test asynchronous code with the [`assert.verifySteps()`](./
 
 | UNRELEASED | `assert.expect()` now counts [`assert.verifySteps()`](./verifySteps.md) as one assertion. Steps no longer count separately.
 
+## Migration guide
+
+If you use `assert.expect()` in combination with `assert.step()` and [`assert.verifySteps()`](../assert/verifySteps.md) in the same test, you previously counted both the steps and the verification of the steps. In QUnit 3.0 this changes to count `assert.verifySteps()` as one assertion instead ([#1226](https://github.com/qunitjs/qunit/issues/1226)).
+
+Before, on QUnit 2.x without [QUnit.config.countStepsAsOne](../config/countStepsAsOne.md):
+
+```js
+QUnit.test('example', async function (assert) {
+  assert.expect(6);
+
+  MyWordParser.on('noun', function (word) {
+    assert.step(word); // 1, 2, 3, 4
+  });
+  var song = await MyWordParser.sing('My Favorite Things', { lines: 1 });
+
+  assert.true(song.finished, 'finished'); // 5
+  assert.verifySteps([ // 6
+    'Raindrops',
+    'roses',
+    'whiskers',
+    'kittens'
+  ]);
+});
+```
+
+After:
+
+```js
+QUnit.test('example', async function (assert) {
+  assert.expect(2);
+
+  MyWordParser.on('noun', function (word) {
+    assert.step(word);
+  });
+  var song = await MyWordParser.sing('My Favorite Things', { lines: 1 });
+
+  assert.true(song.finished, 'finished'); // 1
+  assert.verifySteps([ // 2
+    'Raindrops',
+    'roses',
+    'whiskers',
+    'kittens'
+  ]);
+});
+```
+
 ## Examples
 
 ### Example: No assertions

docs/api/config/countStepsAsOne.md

@@ -0,0 +1,33 @@
+---
+layout: page-api
+title: QUnit.config.countStepsAsOne
+excerpt: Count assert.verifySteps() as one assertion for the assert.expect() count.
+groups:
+  - config
+redirect_from:
+  - "/config/countStepsAsOne/"
+version_added: "2.21.1"
+---
+
+Count `assert.verifySteps()` as one assertion for the `assert.expect()` count.
+
+<table>
+<tr>
+  <th>type</th>
+  <td markdown="span">`boolean`</td>
+</tr>
+<tr>
+  <th>default</th>
+  <td markdown="span">`false`</td>
+</tr>
+</table>
+
+If you have tests that use both `assert.expect()` and `assert.step()` with [`assert.verifySteps()`](../assert/verifySteps.md) in the same test, you may encounter the following warning on QUnit 2.x:
+
+```
+Counting each assert.step() for assert.expect() is changing
+in QUnit 3.0. Omit assert.expect() from tests that use assert.step(),
+or enable QUnit.config.countStepsAsOne to prepare for the upgrade.
+```
+
+Refer to [assert.expect(): Migration guide](../assert/expect.md#migration-guide) for before and after examples.