faker
faker copied to clipboard
Publish both the current and next api docs
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
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.
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
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
This won't work for deprecation / renaming, would it? But it is an interesting idea anyways :thinking:
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.
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
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.
IMO adding @since
or not is a separate issue.
note adding @since
tags now has its own PR: https://github.com/faker-js/faker/pull/1337
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.
In last weeks meeting, we discussed to try a branch-process like this:
![](https://user-images.githubusercontent.com/7195563/193448077-554894ff-7256-4aba-ad96-2ad32588c7fe.png)
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.
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?
Done