[oliwarner]

These release notes really let Rails down. Crowing on about the number of commits and rationalising decisions is a waste of my time, just explain how it's going to make or ruin my day. Links you'd expect to explain features just take you to source files, not documentation. And a HUGE amount of the changes are actually scattered around in sub-project changelogs.

They should look at Django for some inspiration. Here's their latest beta release notes [1]. It's concise, everything links to relevant documentation with examples, and the entire project's changes are handled on the one page. There's even a list of things to check if you're upgrading.

[1]: https://docs.djangoproject.com/en/dev/releases/1.11/

[matt4077]

I think they're excellent – the text is actually interesting to read and it gives me a much better impression of the relativ importance of changes than a simple list would.

I also can't find fault with giving some appreciation to the relevant people who contributed by actually naming them.

[oliwarner]

You'd call the Django release notes a simple list?

My main problem isn't the fluff, it's the lack of real documentation for new features. Or that the link doesn't go to the documentation, it goes to the merged PR on guthub. And that it's very incomplete (see Everything else).

This is not excellent, in that it could keep the things you like and still be much better.

[polutropos]

I found Big Binary's Rails 5 blog more useful than the Rails 5 readme/release notes. Hoping they do the same for 5.1.

http://blog.bigbinary.com/categories/Rails-5

[LouisSayers]

+1 for better release notes - examples would be highly appreciated.

[examancer]

You are comparing release notes for a beta to an actual release. Based on previous rails releases, by the time 5.1 rolls out the releases notes will get much more detailed and resources like guides.rubyonrails.org will be updated to reflect the latest features.

[oliwarner]

The Django notes I looked too are for a beta release too. I agree that it's less important but consistency never hurt.

[andreasklinger]

They switched lately from no-js-needed-ignore-those-fancy-kids to we-now-use-js

Imo worth rationalizing and explaining to their community