feat(phone)!: add new style parameter (#2578)

1 files changed, 15 insertions, 0 deletions

diff --git a/docs/guide/upgrading_v9/2578.md b/docs/guide/upgrading_v9/2578.md
new file mode 100644
index 00000000..cb2963d2
--- /dev/null
+++ b/docs/guide/upgrading_v9/2578.md
@@ -0,0 +1,15 @@
+### faker.phone.number `style` replaces explicit `format`
+
+`faker.phone.number()` generates a phone number for the current locale. However, previously there was little control over the generated number, which might or might not include country codes, extensions, white space and punctuation.
+
+If you wanted more control over the number, it was previously necessary to pass an explicit `format` parameter. This has now been removed. Instead, you can consider one of two options:
+
+1. The new `style` parameter has convenient options for common use cases. There are three possible values.
+
+- - `'human'`: (default, existing behavior) A human-input phone number, e.g. `555-770-7727` or `555.770.7727 x1234`
+- - `'national'`: A phone number in a standardized national format, e.g. `(555) 123-4567`.
+- - `'international'`: A phone number in a E.123 standard international format with country code, e.g. `+15551234567`
+
+The styles are locale-aware, so for example if you use pt_PT, phone numbers suitable for Portugal would be generated.
+
+2. If none of the `style`s match your needs, you can use `faker.string.numeric()` or `faker.helpers.fromRegExp()` to create a custom pattern.