refactor(word)!: change default error strategy to 'fail' (#3560)

1 files changed, 26 insertions, 0 deletions

diff --git a/docs/guide/upgrading.md b/docs/guide/upgrading.md
index a4296059..cea424e1 100644
--- a/docs/guide/upgrading.md
+++ b/docs/guide/upgrading.md
@@ -61,3 +61,29 @@ Some methods do not have exact replacements, so check your code carefully.
 | `faker.image.urlPlaceholder` | `faker.image.dataUri`                                    |
 | `faker.finance.maskedNumber` | See [#3201](https://github.com/faker-js/faker/pull/3201) |
 | `faker.image.avatarLegacy`   | `faker.image.avatar`                                     |
+
+### Word Methods Default Resolution Strategy
+
+The default resolution strategy for the methods in the word module changed to 'fail'.
+This means that methods in the word module will throw an error if no words for your input criteria exist.
+
+```ts
+// There are no nouns between 20-25 characters long in the word list
+faker.word.noun({ length: { min: 20, max: 25 } });
+// In v9, this would return a random noun of any length, like 'plastic'
+// In v10, this throws an error `FakerError: No words found that match the given length.`
+```
+
+Previously, the methods would return a random word, completly ignoring the the length requirements you specified.
+If you want to restore this behaviour, you can provide the 'any-length' strategy to the word methods.
+
+| Method in v9                | Method in v10 with v9 behaviour                       |
+| --------------------------- | ----------------------------------------------------- |
+| `faker.word.adjective()`    | `faker.word.adjective({ strategy: 'any-length' })`    |
+| `faker.word.adverb()`       | `faker.word.adverb({ strategy: 'any-length' })`       |
+| `faker.word.conjunction()`  | `faker.word.conjunction({ strategy: 'any-length' })`  |
+| `faker.word.interjection()` | `faker.word.interjection({ strategy: 'any-length' })` |
+| `faker.word.noun()`         | `faker.word.noun({ strategy: 'any-length' })`         |
+| `faker.word.preposition()`  | `faker.word.preposition({ strategy: 'any-length' })`  |
+| `faker.word.sample()`       | `faker.word.sample({ strategy: 'any-length' })`       |
+| `faker.word.verb()`         | `faker.word.verb({ strategy: 'any-length' })`         |