search

micronaut-projects / micronaut-guides

Guides and Tutorials on how to use Micronaut including sample code
https://guides.micronaut.io
Creative Commons Attribution 4.0 International
35 stars 30 forks source link

Clarify Micronaut version in guides #482

Open burtbeckwith opened 3 years ago

burtbeckwith commented 3 years ago

I've gotten a couple reports from people trying out guides that they fail for older versions of Micronaut. We do specify the Micronaut version at the top, but generally it should be ok be somewhat behind the current version.

We should decide on a standard way to emphasize that users should be using a recent version if they create the app using the cli. It's not an issue if they use Launch or an IDE since those seem to all use Launch.

sdelamo commented 3 years ago

We can communicate that guides for older versions of Micronaut exist.

e.g.

https://guides.micronaut.io/2.5.x/index.html

sdelamo commented 3 years ago

Or maybe explain that Guide URLs use a semantic version:

latest uses the latest stable version of Micronaut:

https://guides.micronaut.io/latest/micronaut-file-download-excel-gradle-java.html

However, we publish guides for a minor of Micronaut:

https://guides.micronaut.io/2.5.x/micronaut-file-download-excel-gradle-java.html

burtbeckwith commented 3 years ago

This would be good especially for users who haven't yet or can't upgrade, but the problems reported to me were that for a 2.5 guide, they were using the 2.4 or earlier CLI to create the initial app and some functionality wasn't available.

The general problem is that although we list the requirements in the "What you will need" section, this is easy to miss/ignore (I assume especially if you've worked through other guides and skip to the main part of the guide).

ilopmar commented 3 years ago

I'm not sure if I understand this correctly. @burtbeckwith are you trying to say that users said that guides for 2.5.x don't work for Micronaut 2.4.x? If that's the case then I think pointing them to the 2.4.x version of the guides (https://guides.micronaut.io/2.4.x/index.html) as Sergio said should be enough. I think it's reasonable that a new feature added for 2.5 is not available in 2.4.

Maybe what we can be more explicit about the Micronaut version with a dropdown like the one we have in the docs:

image

But I'm not sure if doing this is worth it because for it to work we would need to regenerate all guides in previous versions to inlude it. Another approach would be to add a message on at the beginning of the guide explaining that maybe there is a previous version of the guide and that they should take a look at it if they are not using the same Micronaut version as the guide uses.