Versioned documentation or tag this repo
mlvn23 opened this issue · 4 comments
Can we please add a versioned documentation or maybe as a quick hack just tag this repository based on the ScalaJs version release? This way, folks who couldn't upgrade to the latest can check the right documentation. Thanks.
Could you give a concrete example of something that's bothering you? We always keep documentation of all deprecated features on the website, with marks that they are deprecated. So the documentation for older versions is still there, it hasn't disappeared.
@sjrd, first of all, thanks for ScalaJs! I've been re-writing my app in ScalaJs for a few months now, and I couldn't imagine going back to plain JS.
I'm currently using version 0.6.14 and I just saw a new release for 0.6.15. I haven't upgraded to that version yet, because I'm not sure if the other ScalaJs libraries would be compatible.
I was looking at this page to figure out how to call ScalaJs code from JS. First, it does not compile:
[error] D:\extradash\code\src\jvm\midgar\modules\chronos\result-widget\src\main\scala\com\extrategic\chronos\apps\grid\HelloWorld.scala:5: Use @JSExport on objects and constructors to export to the top level
[error] @JSExportTopLevel("HelloWorld")
So I fixed that and just used @JSExport. Then I tried to call it from the JS console:
HelloWorld.sayHello()
VM188:1 Uncaught TypeError: HelloWorld.sayHello is not a function
at <anonymous>:1:12
It turns out HelloWorld is a function, so it must be called HelloWorld().sayHello().
It could be that I just stumbled into a bug in the documentation, but it's more likely because I was using an older version. If I were using an even older version in production, say 0.6.11, I could imagine the "current" documentation to be even more out of sync with what I need. I could read all the changelogs, but that's like reading a few generations of diffs.
There's actually a few instances in the past that I was forced to upgrade so I can be in-sync with the docs, but now that I found this repo, I figure I could just go back in time by looking at the commits. I just thought it would be more convenient if we tag it.
From the PR perspective, it's of course better if there's a versioned documentation on the website. I can imagine someone starting out and trying the ScalaJS SPA app, which could be a few generations behind like today, and reading the docs and find some are not working / in-sync.
I'm currently using version 0.6.14 and I just saw a new release for 0.6.15. I haven't upgraded to that version yet, because I'm not sure if the other ScalaJs libraries would be compatible.
From the release notes (of all versions):
As a minor release, 0.6.15 is backward source and binary compatible with previous releases in the 0.6.x series. Libraries compiled with earlier versions can be used with 0.6.15 without change. However, it is not forward compatible: libraries compiled with 0.6.15 cannot be used by projects using 0.6.{0-14}.
Minor Scala.js releases are always backward source and binary compatible, so old libraries always stay compatible.
I was looking at this page to figure out how to call ScalaJs code from JS. First, it does not compile: [...]
Ah, I see what you mean, now. Indeed, this can be problematic. 0.6.15 especially brought a lot of new features that completely change the good way (i.e., the way explained in the docs first) to do a lot of things. Exports of top-level objects is one of them. Usually, when we update the docs for a new version there is very little change, mostly additions.
Maybe we should add notices in relevant parts of the docs that they apply only to, e.g., 0.6.15+, and that users of older versions should look elsewhere at some particular deprecated feature. I still believe versioned docs are overkill for the typical version-dependent docs that we have.
Yes, I agree that versioned docs would be an overkill. If we could reference somewhere on how do achieve certain things on older versions, that would help.