Publish both the current and next api docs

[ST-DDT]

Clear and concise description of the problem

Multiple users have reported issue caused by the docs page containing docs for the bleeding edge version rather than the current latest release.

• https://github.com/faker-js/faker/discussions/1241
• https://github.com/faker-js/faker/issues/1208
• a few times on discord

Suggested solution

Publish the main docs (page) only during a release. The latest version should be published to next.fakerjs.dev.

Alternative

None

Additional context

No response

[Shinigami92]

The current only way I could imagine of would be to create a next branch that between PRs and the main branch. But I'm not sure if we want the maintenance overhead on our side.

[matthewmayer]

another option could be to add @since tags to the documentation, then each method could be annotated in the docs with which version it was added

https://jsdoc.app/tags-since.html

[Shinigami92]

another option could be to add @since tags to the documentation, then each method could be annotated in the docs with which version it was added

jsdoc.app/tags-since.html

This won't work for deprecation / renaming, would it? But it is an interesting idea anyways :thinking:

[matthewmayer]

I think it might have helped in the fullName example if people could see "added in 7.4.0" in the docs and they know they are using 7.3.1 currently.

[Shinigami92]

But then they would look where v7.4 is released, but there is no v7.4 release and they would ask us for that missing release

So it would move the problem just one issue further

[matthewmayer]

Certainly it doesn't solve the whole problem (I think the solution to only update the docs on the website when you release is sensible)

But it would be useful after releases. If I'm running a version a few minor or patch releases old but am referring to the online documentation.

[ST-DDT]

IMO adding @since or not is a separate issue.

[matthewmayer]

note adding @since tags now has its own PR: https://github.com/faker-js/faker/pull/1337

[ST-DDT]

Thoughts

• Create a next branch and develop there. The next branch will be the default branch.
• The main branch will still be used for the main website, we have to make sure netlify does not take the default branch for the default website.
• This has to be done before development of v8 starts.

[Shinigami92]

In last weeks meeting, we discussed to try a branch-process like this:

Today (in shower :smile:) an issue raised into my mind! What will happen with links to the main branch?

Obviously some of them can just be remapped to the next branch. But some historical links that specifically point to e.g. permalinks, do they need the main branch alive? Or just tweets that contain links referencing the main branch.

[ST-DDT]

But some historical links that specifically point to e.g. permalinks, do they need the main branch alive?

Permalinks reference commits for a reason.

Or just tweets that contain links referencing the main branch.

Why would you reference main explicitly?

[ST-DDT]

Done