As I wrote recently in another post…
I find it hard how every month there’s a new better way to do things, packages that change, packages that might save time but sometimes don’t work well, lots of packages that do the same kind of thing, new versions of meteor… Too much change.
I wonder, how do you approach staying up to date? Sometimes I go to the docs, but I don’t find something that was there yesterday, and I start wondering… am I going crazy? Did this always have this name? Things change and I see nothing mentioning “NEW” or “old way, new way”. If you keep your code as it is, and things keep changing, one year later other people may be unable to work with your code, because it looks very different to what the manual says. How do you stay informed about changes you should implement in your code? I find parsing the release notes to try convert them into decisions to update my code not very efficient and error prone.
Another question is, how do you deal with the possibility that updating meteor and other packages may break your application? Do you have tests for every possible interaction to detect that something starts to fail after an update?
Learning a framework that has a history is always hard, but once you’ve learned how Meteor works today, you can follow the blog to stay updated. They also document changes they make for each new release: https://github.com/meteor/meteor/blob/devel/History.md
But nowadays (when version 1 is out), they no longer make that big changes, do they? They add new features now and then, but they don’t often deprecate/change anything existing.
I understand that it is a changing framework, but there are things that can help deal with that.
The blog does not mention anything about
rendered, created, destroyed and
onError being deprecated. Yes, History.md shows those changes, but they can be lost among lots of other changes we don’t necessarily need to know about to stay up to date.
For instance, I don’t need to do anything about
Improve performance of rendering large arrays. #3596, but I should probably replace
onRendered, or know that the return value from a server-side Meteor.call has changed.
I consider the change on
rendered and friends a big change, because every book and video tutorial out there will mention
rendered, and you won’t find that function on the documentation. You will have to assume somehow that
onRendered means the same as
rendered, which may not be obvious for everyone.
It would help if each line in that History.md would be tagged when it may have implications in our code. That way we can scan history and easily notice that we may have to do something about 5 out of the 50 changes.
It would also help if the documentation included little tags next to each function indicating the version number they were created or modified. That would reduce the possible confusion when you open the documentation and wonder why things look different.
One easy improvement to help with this is offering the documentation like the Django web framework. If you go to their documentation it displays the docs for the latest version but there’s also a button to quickly switch to the docs of older versions.
Would be a nice additional option to add next to the full API / basic docs selector in the Meteor docs.
That way guides/tutorials can simply state at which version of Meteor they were written upon which the reader can quickly get the relevant docs.