diff --git a/content/v2.2/upgrade-notes/.Gemfile.v.2.1.0.swp b/content/v2.2/upgrade-notes/.Gemfile.v.2.1.0.swp new file mode 100644 index 00000000..7a7a4cd0 Binary files /dev/null and b/content/v2.2/upgrade-notes/.Gemfile.v.2.1.0.swp differ diff --git a/content/v2.2/upgrade-notes/Gemfile.v.2.1.0 b/content/v2.2/upgrade-notes/Gemfile.v.2.1.0 new file mode 100644 index 00000000..2ce0a8ea --- /dev/null +++ b/content/v2.2/upgrade-notes/Gemfile.v.2.1.0 @@ -0,0 +1,45 @@ +# frozen_string_literal: true + +source "https://rubygems.org" + +gem "hanami", "~> 2.1.1" +gem "hanami-assets", "~> 2.1" +gem "hanami-controller", "~> 2.1" +gem "hanami-router", "~> 2.1" +gem "hanami-validations", "~> 2.1" +gem "hanami-view", "~> 2.1" + +gem "dry-types", "~> 1.0", ">= 1.6.1" +gem "puma" +gem "rake" +gem "foreman" + + +gem "rom", "~> 5.3" +gem "rom-sql", "~> 3.6" +gem "pg" + + +group :development do + gem "hanami-webconsole", "~> 2.1" + gem "guard" + gem "guard-puma" +end + +group :development, :test do + gem "dotenv" +end + +group :cli, :development do + gem "hanami-reloader", "~> 2.1" +end + +group :cli, :development, :test do + gem "hanami-rspec", "~> 2.1" +end + +group :test do + gem "capybara" + gem "rack-test" + gem "database_cleaner-sequel" +end diff --git a/content/v2.2/upgrade-notes/Gemfile.v.2.2.0 b/content/v2.2/upgrade-notes/Gemfile.v.2.2.0 new file mode 100644 index 00000000..eb1037f4 --- /dev/null +++ b/content/v2.2/upgrade-notes/Gemfile.v.2.2.0 @@ -0,0 +1,41 @@ +# frozen_string_literal: true + +source "https://rubygems.org" + +gem "hanami", "~> 2.2.0.beta" +gem "hanami-assets", "~> 2.2.0.beta" +gem "hanami-controller", "~> 2.2.0.beta" +gem "hanami-db", "~> 2.2.0.beta" +gem "hanami-router", "~> 2.2.0.beta" +gem "hanami-validations", "~> 2.2.0.beta" +gem "hanami-view", "~> 2.2.0.beta" + +gem "dry-types", "~> 1.0", ">= 1.6.1" +gem "dry-operation", github: "dry-rb/dry-operation" +gem "puma" +gem "rake" +gem "sqlite3" + +group :development do + gem "hanami-webconsole", "~> 2.2.0.beta" + gem "guard-puma" +end + +group :development, :test do + gem "dotenv" +end + +group :cli, :development do + gem "hanami-reloader", "~> 2.2.0.beta" +end + +group :cli, :development, :test do + gem "hanami-rspec", "~> 2.2.0.beta" +end + +group :test do + gem "capybara" + gem "rack-test" + gem "pg" + gem "database_cleaner-sequel" +end diff --git a/content/v2.2/upgrade-notes/v2.2.0.md b/content/v2.2/upgrade-notes/v2.2.0.md new file mode 100644 index 00000000..6b2124d1 --- /dev/null +++ b/content/v2.2/upgrade-notes/v2.2.0.md @@ -0,0 +1,431 @@ +--- +title: v2.2.0 +order: 11 +--- + +These notes cover an upgrade from 2.1.0 to 2.2.0. + +## Update the app + +- Edit `Gemfile` and update the versions of the Hanami gems to `"~> 2.2"`. + +- Add the following gems to `Gemfile`: + +```ruby +gem "hanami-db", "~> 2.2.0" +gem "dry-operation", github: "dry-rb/dry-operation" +``` + +- Remove the following gems from `Gemfile`: + +```ruby +gem "rom", "~> 5.3" +gem "rom-sql", "~> 3.6" +``` + + +- Add the following lines to `.gitignore`: + +```text +public/ +node_modules/ +spec/examples.txt +``` + +- Update `Guardfile` to match the following: + +```ruby +group :server do + guard "puma", port: ENV.fetch("HANAMI_PORT", 2300) do + # Edit the following regular expression for your needs. + # See: https://guides.hanamirb.org/app/code-reloading/ + watch(%r{^(app|config|lib|slices)([\/][^\/]+)*.(rb|erb|haml|slim)$}i) + end +end +``` + +- Create `Procfile.dev` and add the following: + +```text +web: bundle exec hanami server +assets: bundle exec hanami assets watch +``` + +- Create `bin/dev`, mark it as executable, (`chmod a+x`) and add the following: + +```shell +#!/usr/bin/env sh + +if ! gem list foreman -i --silent; then + echo "Installing foreman..." + gem install foreman +fi + +exec foreman start -f Procfile.dev "$@" +``` + +- If you are using the default `config/puma.rb`, update it to match the following (note the addition and use of the `puma_concurrency` and `puma_cluster_mode` variables): + +```ruby +# frozen_string_literal: true + +# +# Environment and port +# +port ENV.fetch("HANAMI_PORT", 2300) +environment ENV.fetch("HANAMI_ENV", "development") + +# +# Threads within each Puma/Ruby process (aka worker) +# + +# Configure the minimum and maximum number of threads to use to answer requests. +max_threads_count = ENV.fetch("HANAMI_MAX_THREADS", 5) +min_threads_count = ENV.fetch("HANAMI_MIN_THREADS") { max_threads_count } + +threads min_threads_count, max_threads_count + +# +# Workers (aka Puma/Ruby processes) +# + +puma_concurrency = Integer(ENV.fetch("HANAMI_WEB_CONCURRENCY", 0)) +puma_cluster_mode = puma_concurrency > 1 + +# How many worker (Puma/Ruby) processes to run. +# Typically this is set to the number of available cores. +workers puma_concurrency + +# +# Cluster mode (aka multiple workers) +# + +if puma_cluster_mode + # Preload the application before starting the workers. Only in cluster mode. + preload_app! + + # Code to run immediately before master process forks workers (once on boot). + # + # These hooks can block if necessary to wait for background operations unknown + # to puma to finish before the process terminates. This can be used to close + # any connections to remote servers (database, redis, …) that were opened when + # preloading the code. + before_fork do + Hanami.shutdown + end +end +``` + +- Add the following line to `spec/spec_helper.rb`, underneath the `require_relative "support/rspec"`: + +```ruby +require_relative "support/features" +``` + +- Create `spec/support/features.rb`: + +```ruby +# frozen_string_literal: true + +require "capybara/rspec" + +Capybara.app = Hanami.app +``` + +- If you wish, update `spec/support/rspec.rb` to include the following configs: + +```ruby +config.example_status_persistence_file_path = "spec/examples.txt" + +# Uncomment this to enable warnings. This is recommended, but in some cases +# may be too noisy due to issues in dependencies. +# config.warnings = true +``` + +## Add views + +The steps below apply to each of your app and slices. The code examples use `Bookshelf` as the enclosing Ruby module; replace this with the relevant module for your app or slice. + +- Add a `view.rb` (to `app/` or your slice): + +```ruby +# auto_register: false +# frozen_string_literal: true + +require "hanami/view" + +module Bookshelf + class View < Hanami::View + end +end +``` + +- Add a `views/helpers.rb` (to `app/` or your slice): + +```ruby +# auto_register: false +# frozen_string_literal: true + +module Bookshelf + module Views + module Helpers + # Add your view helpers here + end + end +end +``` + +- Add a `templates/layout/app.html.erb` (to `app/` or your slice): + +```sql + + + + + + Bookshelf + <%= favicon_tag %> + <%= stylesheet_tag "app" %> + + + <%= yield %> + <%= javascript_tag "app" %> + + +``` + +- Create `public/404.html` with the following: + +```html + + + + + + The page you were looking for doesn’t exist (404) + + + + +
+
+

404

+

The page you were looking for doesn’t exist.

+
+
+ + +``` + +- Create `public/500.html` with the following: + +```html + + + + + + We’re sorry, but something went wrong (500) + + + + +
+
+

500

+

We’re sorry, but something went wrong.

+
+
+ + +``` + +## Add assets + +- Create `package.json` with the following: + +```json +{ + "name": "rc3fresh", + "private": true, + "type": "module", + "dependencies": { + "hanami-assets": "^2.1.0" + } +} +``` + +- Run `npm install` + +- Append the following to `Procfile.dev`: + +```text +assets: bundle exec hanami assets watch +``` + +- Create `config/assets.js` with the following: + +```js +import * as assets from "hanami-assets"; + +await assets.run(); + +// To provide additional esbuild (https://esbuild.github.io) options, use the following: +// +// Read more at: https://guides.hanamirb.org/assets/overview/ +// +// await assets.run({ +// esbuildOptionsFn: (args, esbuildOptions) => { +// // Add to esbuildOptions here. Use `args.watch` as a condition for different options for +// // compile vs watch. +// +// return esbuildOptions; +// } +// }); +``` + +- Create `app/assets/css/app.css` (or `assets/css/app.css` in your slice) with the following: + +```css +body { + background-color: #fff; + color: #000; + font-family: sans-serif; +} +``` + +- Create `app/assets/js/app.js` (or `assets/js/app.js` in your slice) with the following: + +```js +import "../css/app.css"; +``` + +- Create `app/assets/images/favicon.ico` (or `assets/images/favicon.ico` in your slice) with the [contents of this file](https://raw.githubusercontent.com/hanami/cli/main/lib/hanami/cli/generators/gem/app/favicon.ico).