docs: create stub for v9 migration guide (#2665)

2 files changed, 5 insertions, 342 deletions

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index eaf99abd..17d7d84d 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -214,7 +214,7 @@ const config: UserConfig<DefaultTheme.Config> = {
             link: '/guide/randomizer',
           },
           {
-            text: 'Upgrading to v8',
+            text: 'Upgrading to v9',
             link: '/guide/upgrading',
           },
         ],
diff --git a/docs/guide/upgrading.md b/docs/guide/upgrading.md
index 85b75268..ae3edaa5 100644
--- a/docs/guide/upgrading.md
+++ b/docs/guide/upgrading.md
@@ -1,350 +1,13 @@
-# Upgrading to v8
+# Upgrading to v9
 
-This is the migration guide for upgrading from v7 to v8.
+This is the migration guide for upgrading from v8 to v9.
 
 ::: info Not the version you are looking for?
 
+- [Upgrading to v8](https://v8.fakerjs.dev/guide/upgrading.html)
 - [Upgrading to v7](https://v7.fakerjs.dev/guide/upgrading.html)
 - [Upgrading to v6](https://v6.fakerjs.dev/migration-guide-v5/)
 
 :::
 
-## Breaking changes
-
-### Removed ability to change the locale on existing `Faker` instances
-
-::: tip Note
-If you are using only the default (`en`) locale, then you don't have to change anything.
-:::
-
-In order to facilitate better and easier locale fallback mechanics, we removed the methods to change the locales on existing `Faker` instances.
-Now, we expose specific faker instances for each locale that you can use:
-
-**Old**
-
-```ts
-import { faker } from '@faker-js/faker';
-
-faker.setLocale('de_CH');
-// or
-faker.locale = 'de_CH';
-faker.localeFallback = 'en';
-```
-
-**New**
-
-```ts
-import { fakerDE_CH as faker } from '@faker-js/faker';
-```
-
-This also fixes issues where more than two locales are required:
-
-**Old**
-
-```ts
-import { faker, Faker } from '@faker-js/faker';
-
-const { de_CH, de, en } = faker.locales;
-const customFaker = new Faker({
-  locale: 'de_CH', // the expected locale
-  localeFallback: 'de', // ensure we have a German fallback for addresses
-  locales: { de_CH, de, en },
-});
-const a = customFaker.internet.email();
-customFaker.locale = 'en'; // neither 'de_CH' nor 'de' have emojis
-const b = customFaker.internet.emoji();
-```
-
-**New**
-
-```ts
-import { base, de, de_CH, en, Faker } from '@faker-js/faker';
-
-// same as fakerDE_CH
-export const customFaker = new Faker({
-  // Now multiple fallbacks are supported
-  locale: [de_CH, de, en, base],
-});
-const a = customFaker.internet.email();
-const b = customFaker.internet.emoji();
-```
-
-If you wish to create entries for multiple locales, you can still do so:
-
-**Old**
-
-```ts
-import { faker } from '@faker-js/faker';
-
-for (let user of users) {
-  const lang = faker.helpers.arrayElement(['de', 'en', 'fr']);
-  faker.locale = lang;
-  user.email = faker.internet.email();
-}
-```
-
-**New**
-
-```ts
-import { faker, fakerDE, fakerEN, fakerFR } from '@faker-js/faker';
-
-for (let user of users) {
-  const currentFaker = faker.helpers.arrayElement([fakerDE, fakerEN, fakerFR]);
-  user.email = currentFaker.internet.email();
-}
-```
-
-For more information refer to our [Localization Guide](localization).
-
-### For missing locale data, Faker will now throw instead of returning `undefined` or `a`-`c`
-
-::: info Note
-The following section mostly applies to custom-built Faker instances.
-:::
-
-Previously, for example if `en` didn't have data for `animal.cat`, then `faker.animal.cat()` would have returned one of `a`, `b` or `c` (`arrayElement`'s default value).
-These values aren't expected/useful as a fallback and potentially also violate the method's defined return type definitions (in case it doesn't return a `string`).
-
-We have now addressed this by changing the implementation so that an error is thrown, prompting you to provide/contribute the missing data.
-This will also give you detailed information which data are missing.
-If you want to check for data you can either use `entry in faker.definitions.category` or use `faker.rawDefinitions.category?.entry` instead.
-
-```ts
-import { es, Faker, fakerES } from '@faker-js/faker';
-
-const fakerES_noFallbacks = new Faker({
-  locale: [es],
-});
-fakerES.music.songName(); // 'I Want to Hold Your Hand' (fallback from en)
-// Previously:
-//fakerES_noFallbacks.music.songName(); // 'b'
-// Now:
-fakerES_noFallbacks.music.songName(); // throws a FakerError
-```
-
-This also has an impact on data that aren't applicable to a locale, for example Hong Kong (`en_HK`) doesn't use ZIP codes/postcodes.
-
-```ts
-import { fakerEN_HK, fakerEN_US } from '@faker-js/faker';
-fakerEN_US.location.zipCode(); // 90210
-fakerEN_HK.location.zipCode(); // throws a FakerError
-```
-
-### `faker.mersenne` and `faker.helpers.repeatString` removed
-
-`faker.mersenne` and `faker.helpers.repeatString` were only ever intended for internal use, and are no longer available.
-
-### `faker.location.zipCodeByState`
-
-The `faker.location.zipCodeByState` method has been deprecated, but will also now throw an error if the current locale does not have a `postcode_by_state` definition.
-
-### Methods will throw on empty data set inputs
-
-The methods `faker.helpers.arrayElement` and `faker.helpers.arrayElements` previously defaulted the `array` argument to a simple string array if none was provided.
-This behavior is no longer supported, as the default value has been removed.
-You are now required to provide an argument.
-
-Additionally, when passing in an empty array argument (`[]`), the functions previously returned `undefined`.
-This behavior violated the expected return type of the method.
-The methods will now throw an `FakerError` instead.
-
-The same thing happens now if you provide an empty object `{}` to `faker.helpers.objectKey` or `faker.helpers.objectValue`.
-
-**Old**
-
-```ts
-const allTags = ['dogs', 'cats', 'fish', 'horses', 'sheep'];
-const tags = faker.helpers.arrayElements(allTags, { min: 0, max: 3 });
-// `tags` might be an empty array which was no problem in v7
-const featuredTag = faker.helpers.arrayElement(tags);
-// `featureTag` will be typed as `string` but could actually be `undefined`
-```
-
-**New**
-
-```ts
-const allTags = ['dogs', 'cats', 'fish', 'horses', 'sheep'];
-const tags = faker.helpers.arrayElements(allTags, { min: 0, max: 3 });
-// `tags` might be an empty array which will throw in v8
-const featuredTag =
-  tags.length === 0 ? undefined : faker.helpers.arrayElement(tags);
-// `featureTag` has to be explicitly set to `undefined` on your side
-
-// OR
-
-const allTags = ['dogs', 'cats', 'fish', 'horses', 'sheep'];
-const tags = faker.helpers.arrayElements(allTags, { min: 0, max: 3 });
-let featuredTag: string | undefined;
-try {
-  featuredTag = faker.helpers.arrayElement(post.tags);
-} catch (e) {
-  // handle error and do something special
-}
-```
-
-### Other deprecated methods removed/replaced
-
-| Old method                      | New method                                                                                             |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `faker.unique`                  | `faker.helpers.unique` (:warning: please check [#1785](https://github.com/faker-js/faker/issues/1785)) |
-| `faker.fake`                    | `faker.helpers.fake`                                                                                   |
-| `faker.commerce.color`          | `faker.color.human`                                                                                    |
-| `faker.company.companyName`     | `faker.company.name`                                                                                   |
-| `faker.phone.phoneNumber`       | `faker.phone.number`                                                                                   |
-| `faker.phone.phoneNumberFormat` | No direct replacement, see documentation for `faker.phone.number`                                      |
-| `faker.phone.phoneFormats`      | No direct replacement, see documentation for `faker.phone.number`                                      |
-| `faker.name.findName`           | _Removed, replace with `faker.person.fullName`_                                                        |
-| `faker.address.cityPrefix`      | _Removed_                                                                                              |
-| `faker.address.citySuffix`      | _Removed_                                                                                              |
-| `faker.address.streetPrefix`    | _Removed_                                                                                              |
-| `faker.address.streetSuffix`    | _Removed_                                                                                              |
-| `faker.image.lorempixel`        | _Removed, as the LoremPixel service is no longer available_                                            |
-
-### Definitions removed
-
-Some data definitions, which were only available via the `faker.helpers.fake` method, or the undocumented `faker.definitions`, have been removed.
-
-| Removed data                                          | Alternative                        |
-| ----------------------------------------------------- | ---------------------------------- |
-| `faker.definitions.business.credit_card_numbers`      | `faker.finance.creditCardNumber()` |
-| `faker.definitions.business.credit_card_types`        | `faker.finance.creditCardIssuer()` |
-| `faker.definitions.business.credit_card_expiry_dates` | `faker.date.future()`              |
-
-## Deprecations and other changes
-
-This is not an exhaustive list of all deprecations in v8.0.0. Many methods and parameters have been renamed in this release. You can:
-
-- use the warnings which are shown at runtime to guide you to the new names
-- use a [suitable plugin](https://www.npmjs.com/package/eslint-plugin-deprecation) to find usages of deprecated code
-- Review the full list of deprecations [here](https://github.com/faker-js/faker/issues?q=label%3Adeprecation+is%3Amerged+milestone%3A%22v8.0+-+Module+Re-Shuffling%22) and [here](https://github.com/faker-js/faker/issues?q=label%3Adeprecation+is%3Amerged+milestone%3A%22v8+-+None+milestone+specific+tasks%22)
-- Ignore the deprecations for now: the old names will continue to work for v8.x.x, however you will need to make changes before upgrading to v9.x.x.
-
-### `faker.name` changed to `faker.person`
-
-The whole `faker.name` module is now located at `faker.person`, as it contains more information than just names.
-The `faker.name.*` methods will continue to work as an alias in v8 and v9, but it is recommended to change to `faker.person.*`
-
-| Old method                 | New method                                      |
-| -------------------------- | ----------------------------------------------- |
-| `faker.name.firstName`     | `faker.person.firstName`                        |
-| `faker.name.lastName`      | `faker.person.lastName`                         |
-| `faker.name.middleName`    | `faker.person.middleName`                       |
-| `faker.name.fullName`      | `faker.person.fullName`                         |
-| `faker.name.gender`        | `faker.person.gender`                           |
-| `faker.name.sex`           | `faker.person.sex`                              |
-| `faker.name.sexType`       | `faker.person.sexType`                          |
-| `faker.name.prefix`        | `faker.person.prefix`                           |
-| `faker.name.suffix`        | `faker.person.suffix`                           |
-| `faker.name.jobTitle`      | `faker.person.jobTitle`                         |
-| `faker.name.jobDescriptor` | `faker.person.jobDescriptor`                    |
-| `faker.name.jobArea`       | `faker.person.jobArea`                          |
-| `faker.name.jobType`       | `faker.person.jobType`                          |
-| `faker.name.findName`      | _Removed, replace with `faker.person.fullName`_ |
-
-### `faker.address` changed to `faker.location`
-
-The whole `faker.address` module is now located at `faker.location`, as it contains more information than just addresses.
-The `faker.address.*` methods will continue to work as an alias in v8 and v9, but it is recommended to change to `faker.location.*`
-
-| Old method                          | New method                           |
-| ----------------------------------- | ------------------------------------ |
-| `faker.address.buildingNumber`      | `faker.location.buildingNumber`      |
-| `faker.address.cardinalDirection`   | `faker.location.cardinalDirection`   |
-| `faker.address.city`                | `faker.location.city`                |
-| `faker.address.cityName`            | `faker.location.city`                |
-| `faker.address.country`             | `faker.location.country`             |
-| `faker.address.countryCode`         | `faker.location.countryCode`         |
-| `faker.address.county`              | `faker.location.county`              |
-| `faker.address.direction`           | `faker.location.direction`           |
-| `faker.address.faker`               | `faker.location.faker`               |
-| `faker.address.latitude`            | `faker.location.latitude`            |
-| `faker.address.longitude`           | `faker.location.longitude`           |
-| `faker.address.nearbyGPSCoordinate` | `faker.location.nearbyGPSCoordinate` |
-| `faker.address.ordinalDirection`    | `faker.location.ordinalDirection`    |
-| `faker.address.secondaryAddress`    | `faker.location.secondaryAddress`    |
-| `faker.address.state`               | `faker.location.state`               |
-| `faker.address.stateAbbr`           | `faker.location.stateAbbr`           |
-| `faker.address.street`              | `faker.location.street`              |
-| `faker.address.streetAddress`       | `faker.location.streetAddress`       |
-| `faker.address.streetName`          | `faker.location.street`              |
-| `faker.address.timeZone`            | `faker.location.timeZone`            |
-| `faker.address.zipCode`             | `faker.location.zipCode`             |
-| `faker.address.zipCodeByState`      | `faker.location.zipCodeByState`      |
-| `faker.address.cityPrefix`          | _Removed_                            |
-| `faker.address.citySuffix`          | _Removed_                            |
-| `faker.address.streetPrefix`        | _Removed_                            |
-| `faker.address.streetSuffix`        | _Removed_                            |
-
-### Number methods of `faker.datatype` moved to new `faker.number` module
-
-The number-related methods previously found in `faker.datatype` have been moved to a new `faker.number` module.
-For the old `faker.datatype.number` method you should replace with `faker.number.int` or `faker.number.float` depending on the precision required.
-
-By default, `faker.number.float` no longer defaults to a precision of 0.01
-
-```js
-// OLD
-faker.datatype.number(); // 88999 (NOTE: The default max was 99999)
-faker.datatype.number({ max: 100 }); // 35
-faker.datatype.number({ max: 100, precision: 0.01 }); // 35.21
-faker.datatype.float({ max: 100 }); // 35.21
-faker.datatype.float({ max: 100, precision: 0.001 }); // 35.211
-
-// NEW
-faker.number.int({ max: 99999 }); // 88999 (NOTE: the default max is now Number.MAX_SAFE_INTEGER)
-faker.number.int({ max: 100 }); // 35
-faker.number.float({ max: 100 }); // 35.21092065742612
-faker.number.float({ max: 100, precision: 0.01 }); // 35.21
-```
-
-| Old method              | New method                                 |
-| ----------------------- | ------------------------------------------ |
-| `faker.datatype.number` | `faker.number.int` or `faker.number.float` |
-| `faker.datatype.float`  | `faker.number.float`                       |
-| `faker.datatype.bigInt` | `faker.number.bigInt`                      |
-
-### Deprecation of `faker.datatype.array`
-
-The method `faker.datatype.array` has been deprecated and will be removed in v9.
-If you need an array of useful values, you are better off creating your own one using `faker.helpers.multiple`.
-
-### `faker.datatype.datetime` deprecated in favor of `faker.date.between` and `faker.date.anytime`
-
-The `datetime` method previously found in `faker.datatype` has been deprecated, use `faker.date.between` or `faker.date.anytime` instead.
-
-### `faker.helpers.regexpStyleStringParse` deprecated in favor of `faker.helpers.fromRegExp`
-
-The `regexpStyleStringParse` method in `faker.helpers` has been deprecated in Faker 8.1. A likely replacement is the more powerful `faker.helpers.fromRegExp`.
-
-```js
-faker.helpers.regexpStyleStringParse('a{3,6}'); // aaaaa
-faker.helpers.fromRegExp('a{3,6}'); // aaaaa
-```
-
-However, please note that `faker.helpers.fromRegExp` is not an exact replacement for `faker.helpers.regexpStyleStringParse` as `fromRegExp` cannot handle numeric ranges. This will now need to be handled separately.
-
-```js
-faker.helpers.regexpStyleStringParse('a{3,6}[1-100]'); // "aaaa53", etc.
-faker.helpers.fromRegExp('a{3,6}') + faker.number.int({ min: 1, max: 100 });
-```
-
-### `allowLeadingZeros` behavior change in `faker.string.numeric`
-
-The `allowLeadingZeros` boolean parameter in `faker.string.numeric` (in the new `string` module) now defaults to `true`. `faker.string.numeric` will now generate numeric strings that could have leading zeros by default.
-
-### Simplified MIME type data
-
-The functions `faker.system.mimeType`, `faker.system.fileType` and `faker.system.fileExt` now return data from a smaller set of more common MIME types, filetypes and extensions.
-
-### `faker.helpers.unique` is planned to be outsourced
-
-The `faker.helpers.unique` method is planned to be outsourced to a separate package.  
-Please check issue [#1785](https://github.com/faker-js/faker/issues/1785) for more details.
-
-### Locales renamed
-
-The `en_IND` (English, India) locale was renamed to `en_IN` for consistency with other locales.
-
-The `cz` (Czech) locale was renamed to `cs_CZ` to use the standard ISO codes for language and country.
-
-The `ge` (Georgian) locale was renamed to `ka_GE` to use the standard ISO codes for language and country.
+v9 has not yet been released. This page will contain a work-in-progress list of breaking changes in v9.