search

marko-js / marko

A declarative, HTML-based language that makes building web apps fun
https://markojs.com/
MIT License
13.4k stars 644 forks source link

Please keep Changelog up to date #46

Closed barwin closed 9 years ago

barwin commented 9 years ago

Especially with regards to breaking changes and feature deprecations.

It will help us make informed decisions about if/when to upgrade and what app-changes we need to make to stay up to date with the latest and greatest.

We have gotten ourselves into trouble a few times with mismatched versions between marko and supporting modules. I think having an accurate Changelog on each module would be hugely helpful in tracking down where we went awry.

Thanks!

philidem commented 9 years ago

I agree. The interdependencies between modules and out-of-date modules can cause some strangeness. Besides keeping the changelog up-to-date, we should see if there is a way to detect incompatibilities at runtime when in development mode (might be a tooling issue). Perhaps something that could inspect the package.json and node_modules to look for inconsistencies.

barwin commented 9 years ago

Thanks @philidem -- That sounds like it would be a big help!

patrick-steele-idem commented 9 years ago

Hi @barwin. We do maintain a CHANGELOG.md for Marko: https://github.com/raptorjs/marko/blob/master/CHANGELOG.md

However, I think an "Upgrade Guide" is needed as well to describe what steps should be taken to upgrade to a new major version. This would be similar to the "Upgrade Guide" added for Marko Widgets: https://github.com/raptorjs/marko-widgets/blob/master/CHANGELOG.md#upgrade-guide

Any other suggestions for making the changelog better?

barwin commented 9 years ago

Hi @patrick-steele-idem,

I think the Marko ChangeLog was a bit out of date when I opened this issue, but it seems to be all caught up now. Thanks for that! (Or, I may just be crazy ...)

Upgrade guides are definitely fantastic help, and much appreciated.

It seems some supporting modules don't have ChangeLogs, however, and that's what I was trying to get at in my initial message. Here are a few, as examples: raptorjs/optimizer, raptorjs/optimizer-marko, raptorjs/optimizer-less.

Maybe it wouldn't be practical or helpful to have Changelogs for each .. I'm not sure. As a Marko-user, it's probably easier to have a single ChangeLog/Upgrade guide to follow. But the interdependencies between modules complicates things.

I like @philidem's suggestion of having some runtime detection of incompatibilities.

Meanwhile, I'm using 'npm shrinkwrap' to freeze my module versions so that any future upgrades are deliberate and that is a working solution for me, for now.

Thank you for the great project!

-Ben