What's new?

You can get a taste for the new stuff in the 0.9.0 release from the ChangeLog page. In general, this is a very stable, well-tested release. The beta is being actively used in a number of production sites, including this one, with no reported ill effects. The Yesod team feels very strongly that this is an upgrade worth making as soon as possible.

The purpose of the release candidate is to try to get any last-minute input on bugs or bad decisions before they are set in stone with the official release. I highly encourage everyone using Yesod to install the release candidate and test it out on a few of your sites.

Get set up for Yackage

The 0.9 release candidate is available on the Yesod Yackage server. Note that the version numbers are the same as will be released with the final release. That means that, if you install the RC, it's highly recommended to wipe your .ghc folder after the official release comes out.

In order to install the release candidate, follow these steps:

1. Add the following line to your ~/.cabal/config file:

   remote-repo: yesod-yackage:http://yackage.yesodweb.com

2. Run cabal update
3. Run cabal install yesod-0.9.0
4. Get a beer and congratulate yourself on a job well done.

Migration guide: Yesod 0.8 to 0.9

As has become a bit of a custom, we're going to go through the necessary changes to the Haskellers codebase to get it to work with the new release. Fortunately, there are many less steps in this release. You can see the entire commit on Github. To give you an idea of time investment, it took me about two hours to migrate Haskellers, write this guide, and apply a few minor tweaks to the framework in the process.

1. Fix up your cabal file. For the most part, just change yesod to version 0.9 and watch the fallout. Pay particular attention to the version bounds on related packages like hamlet and persistent. Also:
   • hamlet has been split out into multiple packages. You'll likely get build errors telling you to add shakespeare-css and shakespeare-js
   • Due to issues with the newest aeson and Template Haskell, we had to create a fork. The API is identical, the only difference is in how doubles are rendered. Just updated any references to aeson to be aeson-native.
2. Goodbye "Helpers" module namespace. This affects Yesod.Helpers.Static, Yesod.Helpers.Auth.*, Yesod.Helpers.Feed.* and others. All you need to do is remove the word Helpers.
3. The datatypes from hamlet have been renamed. This likely doesn't affect much code, but just be aware of it.

   Old name	New name
   Hamlet	HtmlUrl
   Cassius/Lucius	CssUrl
   Julius	JavascriptUrl
   IHamlet	HtmlUrlI18n

4. Forms have had a significant overhaul. This will be the most labor-intensive part of the migration. I'll address this later.
5. In your Model.hs file, mkPersist now takes an extra parameter to give it settings. For now use sqlSettings, we'll have some more options in the future.
6. Model.hs needs the GADTs language extension enabled.
7. In your application file (e.g., Haskellers.hs), remove the type synonyms for Handler and Widget. This is now provided by the TH code. Also, instead of Widget (), just say Widget.
8. In the YesodPersist instance, change "YesodDB" to "YesodPersistBackend".
9. The other big change: the filter API for persistent became much simpler. Instead of using constructors like "PersonNameEq", we now just use operators. (Thanks to Boris for the groundhog inspiration here.) Some simple examples:

   Old code	New code
   PersonNameEq "Michael"	PersonName ==. "Michael"
   PersonAgeLe 30	PersonAge <=. 30
   UserEmailNe $ Just "[email protected]"	UserEmail !=. Just "[email protected]"

   There will be a bit of manual effort involved in this transition, but the result is well worth it.
10. select syntax has changed. Instead of having those two hanging integers at the end, we have a list of options. An example should suffice:

    Old

    selectList [PersonNameEq "Michael"] [PersonAgeDesc] 5 10

    New

    selectList [PersonName ==. "Michael"] [Desc PersonAge, LimitTo 5, OffsetBy 10]

    If you had a 0 for either of those trailing integers, they can just be ignored.
11. Updates are similarly changed.

    Old

    update personId [PersonName "Michael"]

    New

    update personId [PersonName =. "Michael"]

12. And a great sigh of relief was heard: polymorphic hamlet is gone. For the most part, this just means you'll need to preface a few hamlet calls with toWidget. Unfortunately, the error messages are confusing; just email the list if you get stuff on somthing.
13. There have been some renames in the templates. It's best to just read the chapter for details.
14. We added i18n support for form messages. You'll need to add this to your application file (e.g., Haskellers.hs)

    instance RenderMessage Haskellers FormMessage where
        renderMessage _ _ = defaultFormMessage

    This uses the default values, which are all English. You can modify these yourself if you want, expect some blog posts in the next few weeks focusing on how i18n works.
15. Under some strange conditions, you'll have to give your ID variables explicit type signatures. This is exceedingly rare.