Skip to content
Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
572 lines (393 sloc) 15.9 KB

Upgrading from 0.12 to 0.13

  • Upgrade Lucky CLI (macOS)
brew update
brew upgrade crystal-lang # Make sure you're up-to-date. Requires 0.27.2
brew upgrade lucky
  • Upgrade Lucky CLI (Linux)

  • Update .crystal-version to 0.27.2

Remove the existing Lucky binary and follow the Linux instructions in this section https://luckyframework.org/guides/installing/#install-lucky

  • Update versions in shard.yml

    • Lucky should be ~> 0.13
    • LuckyFlow should be ~> 0.4
    • Authentic should be ~> 0.3
  • Run shards update

  • Find and replace LuckyRecord with Avram

  • Add Lucky::AssetHelpers.load_manifest below require "dependencies" in src/app.cr for browser apps. Skip for API only apps.

  • Query#preload with a query now includes the association name -> Query#preload_{{ assoc_name }}

  • Remove unexpose and unexpose_if_exposed from your actions. Pages now ignore unused exposures so these methods have been removed.

  • Change require "lucky_record" to require "avram" in src/dependencies

  • Rename config/log_handler.cr to config/logger.cr

  • Replace config/logger.cr with this:

require "file_utils"

logger =
  if Lucky::Env.test?
    # Logs to `tmp/test.log` so you can see what's happening without having
    # a bunch of log output in your specs results.
    FileUtils.mkdir_p("tmp")
    Dexter::Logger.new(
      io: File.new("tmp/test.log", mode: "w"),
      level: Logger::Severity::DEBUG,
      log_formatter: Lucky::PrettyLogFormatter
    )
  elsif Lucky::Env.production?
    # This sets the log formatter to JSON so you can parse the logs with
    # services like Logentries or Logstash.
    #
    # If you want logs like in develpoment use `Lucky::PrettyLogFormatter`.
    Dexter::Logger.new(
      io: STDOUT,
      level: Logger::Severity::INFO,
      log_formatter: Dexter::Formatters::JsonLogFormatter
    )
  else
    # For development, log everything to STDOUT with the pretty formatter.
    Dexter::Logger.new(
      io: STDOUT,
      level: Logger::Severity::DEBUG,
      log_formatter: Lucky::PrettyLogFormatter
    )
  end

Lucky.configure do |settings|
  settings.logger = logger
end

Avram::Repo.configure do |settings|
  settings.logger = logger
end
  • If using is in queries, rename the calls to eq

  • App in src/app.cr should now inherit from Lucky::BaseApp. See the changes you need to make.

  • Move bin/setup to script/setup

  • In your README replace bin/setup with script/setup

  • Replace bin/lucky in your .gitignore with just /bin/. Lucky projects should now put bash scripts in /script. Binaries go in /bin/ and are ignored.

  • id in actions using route now have the underscored version of the resource name prepended. You'll need to rename your id calls to <resource_name>_id.

# Example from v0.12
class Users::Show < BrowserAction
  route do
    # Using the 'id' param
    UserQuery.find(id)
  end
end

# Would now be
class Users::Show < BrowserAction
  route do
    # Now it is 'user_id'
    UserQuery.find(user_id)
  end
end

And you should now be good to go!

Upgrading from 0.11 to 0.12

  • Upgrade Lucky CLI (macOS)
brew update
brew upgrade crystal-lang # Make sure you're up-to-date. Requires 0.27
brew upgrade lucky
  • Upgrade Lucky CLI (Linux)

Remove the existing Lucky binary and follow the Linux instructions in this section https://luckyframework.org/guides/installing/#install-lucky

Use your package manager to update Crystal to v0.27

  • In db/migrations, change LuckyMigrator::Migration -> LuckyRecord::Migrator::Migration for every migration

  • Remove lucky_migrator from shard.yml

  • Remove lucky_migrator from src/dependencies

  • Remove the LuckyMigrator.configure block from config/database.cr

  • Configuration now requires passing an argument. Find and replace .configure do with .configure do |settings| in all files in config

  • Update config/session.cr

    • Change Lucky::Session::Store.configure to Lucky::Session.configure do |settings|

    • Change your session key because signing/encryption has changed. For example: add _0_12_0 to the end of the key.

    • Remove settings.secret = Lucky::Server.settings.secret_key_base

  • If using cookies[] anywhere in your app, change the key you use. Lucky now signs and encrypts all cookies. Old cookies will not decrypt properly.

  • Change session[]= and cookies[]= to session|cookies.set|get

  • Change session|cookies.destroy to session/cookies.clear

  • cookies.unset(:key) and delete.unset(:key) should be cookies|session.delete(:key)

  • Remove unexpose current_user from src/actions/home/index.cr

  • Query#count has been renamed to Query#select_count. For example: UserQuery.new.count is now UserQuery.new.select_count

  • Change flash.danger to flash.failure in your actions.

  • Update Lucky::Flash::Handler to Lucky::FlashHandler in src/app.cr

  • Update usages of Lucky::Response to Lucky::TextResponse

  • Update usages of LuckyInflector::Inflector to Wordsmith::Inflector

  • Remove config/session.cr and copy config/cookies.cr

  • Replace config/email.cr with this one.

  • Add this line to spec_helper.cr (around line 19) -> LuckyRecord::Migrator::Runner.new.ensure_migrated!

  • In config/server.cr, copy the new block starting at line 15.

  • Update shard versions in shard.yml:

    • Lucky ~> 0.12
    • LuckyRecord ~> 0.7
    • Authentic ~> 0.2
    • LuckyFlow ~> 0.3
  • Change .crystal-version to 0.27.0

  • Run shards update to install the new shards

Upgrading from 0.10 to 0.11

  • Upgrade Lucky CLI (macOS)
brew update
brew upgrade crystal-lang # Make sure you're up-to-date
brew upgrade lucky
  • Upgrade Lucky CLI (Linux)

Remove the existing Lucky binary and follow the Linux instructions in this section https://luckyframework.org/guides/installing/#install-lucky

Use your package manager to update Crystal to v0.25

Upgrading from 0.8 to 0.10

Note: Lucky skipped version 0.9 so that Lucky and Lucky CLI are on the same version.

  • Upgrade Lucky CLI

On macOS:

brew update
brew upgrade crystal-lang # Make sure you're up-to-date
brew upgrade lucky

If you are on Linux, remove the existing Lucky binary and follow the Linux instructions in this section https://luckyframework.org/guides/installing/#install-lucky

  • View the upgrade diff and make changes to your app

In previous upgrade guides (below) every change is listed individually. This was time consuming and error-prone. Now, you can view all changes in this GitHub commit.

  • Ensure node version is at least 6.0 node -v. Install a newer version if yours is older.

  • Move files in src/pipes to src/actions/mixins

  • Change allow to fillable in forms

  • Change allow_virtual to virtual in forms

  • Run shards update

  • Run bin/setup to run new migrations, Laravel Mix and seeds file

If you have any problems or want to add extra details please open an issue or Pull Request. Thank you!

Upgrading from 0.7 to 0.8

  • Upgrade Lucky CLI

On macOS:

brew update
brew upgrade crystal-lang
brew upgrade lucky

If you are on Linux, remove the existing Lucky binary and follow the Linux instructions in this section: https://luckyframework.org/guides/installing/#install-lucky

  • Update dependencies in shard.yml
dependencies:
  lucky:
    github: luckyframework/lucky
    version: "~> 0.8.0"
  lucky_migrator:
    github: luckyframework/lucky_migrator
    version: ~> 0.4.0

Then run shards update

  • Update config/server.cr

You can probably copy this as-is, but if you have made customizations to your config/server.cr then you'll need to customize this:

Lucky::Server.configure do |settings|
  if Lucky::Env.production?
    settings.secret_key_base = secret_key_from_env
    settings.host = "0.0.0.0"
    settings.port = ENV["PORT"].to_i
  else
    settings.secret_key_base = "<%= secret_key_base %>"
    # Change host/port in config/watch.yml
    # Alternatively, you can set the PORT env to set the port
    settings.host = Lucky::ServerSettings.host
    settings.port = Lucky::ServerSettings.port
  end
end

private def secret_key_from_env
  ENV["SECRET_KEY_BASE"]? || raise_missing_secret_key_in_production
end

private def raise_missing_secret_key_in_production
  raise "Please set the SECRET_KEY_BASE environment variable. You can generate a secret key with 'lucky gen.secret_key'"
end
  • Add config/watch.yml

This is used by the watcher so it knows what port the server is running on.

host: 0.0.0.0
port: 5000
  • Update config/database.cr

Put this inside of the LuckyRecord::Repo.configure do |settings| block:

# In development and test, raise an error if you forget to preload associations
settings.lazy_load_enabled = Lucky::Env.production?

See a full example here: https://github.com/luckyframework/lucky_cli/blob/a25472cc7461b1803735d086e57a632f92f93a1c/src/web_app_skeleton/config/database.cr.ecr

  • You will need to preload associations now:

This will make N+1 queries a thing of the past.

# Will now raise a runtime error in dev/test
post = PostQuery.new.find(id)
post.comments # Must preload comments

# Now, you need to preload the comments
post = PostQuery.new.preload_comments.find(id)
post.comments
  • Rename field to column in your models. For example
class Post < BaseModel
  table :posts do
    column title : String # was "field title : String" previously
  end
end
  • Optionally include responsive_meta_tag in MainLayout

You can include this in head to make your app layout responsive.

  • Change abstract def inner to abstract def content in MainLayout

  • Change method call to inner to content in the render method of MainLayout

  • Change instances of def inner to def content in Pages

  • Change form needs to use on: :create

needs in forms should now use on: :save if you want the old behavior.

See https://luckyframework.org/guides/saving-with-forms/#passing-extra-data-to-forms for more info

  • Must pass extra params using create or update

You can no longer pass params to Form#new. You must pass them in the create or update.

UserForm.new(name: "Jane").save!
UserForm.create!(name: "Jane")

More info at https://luckyframework.org/guides/saving-with-forms/#passing-data-without-route-params

  • Change calls from form.save_succeeded? to form.saved?

  • Trap int in src/server.cr

Add this to your src/server.cr before server.listen

Signal::INT.trap do
  server.close
end
  • Add bin/lucky/ to .gitignore
# Add to .gitignore
bin/lucky/
  • Add nice HTML error page

Copy contents of the linked file to src/pages/errors/show_page.cr https://github.com/luckyframework/lucky_cli/blob/a25472cc7461b1803735d086e57a632f92f93a1c/src/web_app_skeleton/src/pages/errors/show_page.cr

  • Add default Error::ShowSerializer

This is used for serializering errors to JSON. Add this to src/serializers/errors/show_serializer.cr

# This is the default error serializer generated by Lucky.
# Feel free to customize it in any way you like.
class Errors::ShowSerializer < Lucky::Serializer
  def initialize(@message : String, @details : String? = nil)
  end

  def render
    {message: @message, details: @details}
  end
end
  • Update Errors::Show action

The error handling action now supports more errors and renders better output.

Copy the contents of the linked file to src/actions/errors/show.cr https://github.com/luckyframework/lucky_cli/blob/a25472cc7461b1803735d086e57a632f92f93a1c/src/web_app_skeleton/src/actions/errors/show.cr

  • Require serializers

Add the following to src/app.cr.

require "./serializers/**"

Upgrading from 0.6 to 0.7

  • Update to Crystal v0.24.1. Lucky will fail on earlier versions
brew update
brew upgrade crystal-lang
brew upgrade lucky

If you are on Linux, remove the existing Lucky binary and follow the Linux instructions in this section: https://luckyframework.org/guides/installing/#install-lucky

  • Update dependencies in shard.yml
dependencies:
  lucky:
    github: luckyframework/lucky
    version: "~> 0.7.0"
  lucky_migrator:
    github: luckyframework/lucky_migrator
    version: ~> 0.4.0

Then run shards update

  • Configure the domain to use for the RouteHelper:
# Add to config/route_helper.cr
Lucky::RouteHelper.configure do |settings|
  if Lucky::Env.production?
    # The APP_DOMAIN is something like https://myapp.com
    settings.domain = ENV.fetch("APP_DOMAIN")
  else
    settings.domain = "http:://localhost:3001"
  end
end
  • Add csrf_meta_tags to your MainLayout
# src/pages/main_layout.cr
# Somewhere in the head tag:
csrf_meta_tags
  • Remove needs flash from MainLayout
# Delete this line
needs flash : Lucky::Flash::Store
  • Remove expose flash from BrowserAction and add forgery protection
# src/actions/browser_action.cr
abstract class BrowserAction < Lucky::Action
  include Lucky::ProtectFromForgery
end
  • Change Shared::FlashComponent to get the flash from @context
# src/components/shared/flash_component.cr
# Change this:
@flash.each
# To:
@context.flash.each
  • Add *.dwarf to the .gitignore
# Add to .gitignore
*.dwarf
You can’t perform that action at this time.