Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: blog post v9.0 #3056

Draft
wants to merge 3 commits into
base: next
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 106 additions & 0 deletions docs/about/announcements/2024-08-31-whats-new-in-9-0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
# What's New In v9.0

::: info Looking for the migration guide?
This article is a focusing on changes happened in the development of v9 that are on the more interesting side.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This article is a focusing on...

Should be

This article focuses on...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are even more grammatical issues, so maybe just paste the blog into another spellchecking tool and fix them with one commit

If you are just looking for a way to migrate from v8 to v9 check out our [migration guide](https://v9.fakerjs.dev/guide/upgrading).
:::

## Optimizing Bundle Size with Tree-Shaking

In the upcoming release of Faker.js, we’ve tackled an important issue related to bundle size. The problem? Unnecessary modules were being included during tree-shaking, leading to bloated final bundles. But fear not! We’ve got a solution.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO we should not refer to upcoming release, as the blog will either be merged either right before the major release or afterwards.


The root problem was located in the way we handled locale imports and exports. Previously, the `allLocales` variable was defined using a named wild card export (`export * as <name> from '<path>'`). We refactored this into an named variable export. Additionally, we updated the package.json file to specify `"sideEffects": false`, signaling to bundlers that all files within this package are side-effect-free and can be safely tree-shaken.

The results speak for themselves.

| v8.4.1 | v9.0.0 |
| -------- | ------- |
| 2.77 MiB | 438 KiB |

That’s a significant reduction of around 84.5% in file size!

## Use High Precision RNG by Default

In v9 we switch from a 32 bit random value to a 53 bit random value.
We don't change the underlying algorithm much, but we now consume two seed values each step instead of one.
This affects generated values in two ways:

- In large lists or long numbers the values are spread more evenly.
This also reduces the number of duplicates it generates.
For `faker.number.int()` this reduces the number of duplicates from `1 / 10_000` to less than `1 / 8_000_000`.
- If you start with the same initial seed to generate a value, you might see some changes in the results you get.
This is because we're now working with a higher precision, which affects how numbers are rounded off.
As a result, the methods we use might produce slightly different outcomes.
And since we are now using two seed values each time subsequent results appear to skip a value each time.

```ts
import {
SimpleFaker,
generateMersenne32Randomizer,
generateMersenne53Randomizer,
} from '@faker-js/faker';

// < v9 default
const oldFaker = new SimpleFaker({
randomizer: generateMersenne32Randomizer(),
});
oldFaker.seed(123);
const oldValue = oldFaker.helpers.multiple(() => oldFaker.number.int(10), {
count: 10,
});
// > v9 default
const newFaker = new SimpleFaker({
randomizer: generateMersenne53Randomizer(),
});
newFaker.seed(123);
const newValue = newFaker.helpers.multiple(() => newFaker.number.int(10), {
count: 5,
});

diff(oldValue, newValue);
//[
// 7,
// 7, // [!code --]
// 3,
// 4, // [!code --]
// 2,
// 7, // [!code --]
// 6,
// 7, // [!code --]
// 7,
// 5, // [!code --]
//]
```

## New Modules

We are thrilled to announce the latest addition to FakerJS – the [FoodModule](https://v9.fakerjs.dev/api/food.html)!
Whether you’re building a restaurant app, a food blog, or just need some delicious data for testing, the Food Module has got you covered.
From spices to vegetables, meats, and fruits, you can generate a wide variety of ingredients to spice up your data.
Or make your applications more engaging with unique and mouth-watering dish names and descriptions.
Whether you need a single ingredient or a full menu, the Food Module offers the flexibility to meet your needs.

Additionally, the [MusicModule](https://v9.fakerjs.dev/api/music.html) now featuring two brand-new methods: `album()` and `artist()`!
These additions will enhance your music-related projects by providing more detailed and diverse data.
Get the update and enjoy the latest tunes!

## Release Automation

In our continuous effort to streamline and enhance the release process for Faker, we recently implemented the first steps required for our automated release pipeline.
This initiative aims to improve efficiency, reduce manual errors, and ensure a smoother release cycle.
Matter of fact this version was released using our new process.

Our new process consists of 4 key steps:

1. [Create a release Pull Request](https://github.com/faker-js/faker/pull/2981)
1. [Have an additional CI suite that tests against our playground](https://github.com/faker-js/faker/pull/2988)
1. [Create a GitHub Release](https://github.com/faker-js/faker/pull/2990)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO we should refer to this as Draft a GitHub release

1. [Release the latest version to npm](https://github.com/faker-js/faker/pull/2991)
Comment on lines +95 to +98
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we number these correctly even if GH/vitepress fixes them automatically?

Comment on lines +95 to +98
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO we should refer to this step as Publish the ...


This allows us to kick off the process with a single manual schedule of the PR creation job.
This PR will then run an additional test CI (in parallel to our normal one) against our [playground repo](https://github.com/faker-js/playground).
If the PR is successfully merged another job is automatically started to create a draft GitHub Release.
This allows us to verify the correctness of the release one last time.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO this isn't the main point of that step, IMO it just gives us the ability to edit the GitHub release to our needs.
But I'm not sure whether that is nitpicking or not.

By publishing the GitHub release, the last job will kick in to publish this release to npm.
All these steps where done manually by the maintainers, previously.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add a little bit of "why" here aka "and sometimes we forgot them or did them in the wrong order"


42 changes: 1 addition & 41 deletions docs/guide/upgrading.md
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should have a link to the announcement blog page

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean on the top of the file. Same as the announcement has towards the upgrading site?

Original file line number Diff line number Diff line change
Expand Up @@ -60,50 +60,10 @@ While this is not a breaking change according to semantic versioning guidelines,

### Use High Precision RNG by Default

TLDR: Many Faker methods return a different result in v9 compared to v8 for the same seed.

In v9 we switch from a 32 bit random value to a 53 bit random value.
We don't change the underlying algorithm much, but we now consume two seed values each step instead of one.
xDivisionByZerox marked this conversation as resolved.
Show resolved Hide resolved
This affects generated values in two ways:

- In large lists or long numbers the values are spread more evenly.
This also reduces the number of duplicates it generates.
For `faker.number.int()` this reduces the number of duplicates from `1 / 10_000` to less than `1 / 8_000_000`.
- If you start with the same initial seed to generate a value, you might see some changes in the results you get.
This is because we're now working with a higher precision, which affects how numbers are rounded off.
As a result, the methods we use might produce slightly different outcomes.
And since we are now using two seed values each time subsequent results appear to skip a value each time.

```ts
import {
SimpleFaker,
generateMersenne32Randomizer,
generateMersenne53Randomizer,
} from '@faker-js/faker';

// < v9 default
const f32 = new SimpleFaker({ randomizer: generateMersenne32Randomizer() });
f32.seed(123);
const r32 = f32.helpers.multiple(() => f32.number.int(10), { count: 10 });
// > v9 default
const f53 = new SimpleFaker({ randomizer: generateMersenne53Randomizer() });
f53.seed(123);
const r53 = f53.helpers.multiple(() => f53.number.int(10), { count: 5 });

diff(r32, r53);
//[
// 7,
// 7, // [!code --]
// 3,
// 4, // [!code --]
// 2,
// 7, // [!code --]
// 6,
// 7, // [!code --]
// 7,
// 5, // [!code --]
//]
```
You can read more in out Blog Post: [What's New In v9.0](/about/announcements/2024-08-31-whats-new-in-9-0#use-high-precision-rng-by-default)

#### Adoption

Expand Down