From de963c53d0717dd06b46a1d048c8a5f5a0b601d7 Mon Sep 17 00:00:00 2001 From: Dani Bengl Date: Tue, 5 May 2026 23:03:27 +0200 Subject: [PATCH 1/2] Improve docs: linearize ASG, refresh content, restructure - Linearize Application Setup Guide into sequential numbered steps - Refresh Bootstrap recipe and Wicked PDF instructions - Update README, SUMMARY, naming conventions - Various phrasing and formatting cleanups across guides - Update Gitlab hint, mdbook command examples - Add template-repo comments to Rails docs Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 47 ++++---- SUMMARY.md | 64 ++++++----- configure_git_repository.md | 17 ++- create_git_repository.md | 2 +- google_analytics.md | 2 +- naming_conventions.md | 16 +-- ruby_on_rails/README.md | 107 ++++++++++-------- ruby_on_rails/app_initialisation.md | 36 +++--- ruby_on_rails/compile_readme.md | 4 - ruby_on_rails/configure_ci.md | 4 +- ruby_on_rails/content_security_policy.md | 2 +- .../create_application_server_deploio.md | 11 +- ruby_on_rails/cucumber.md | 2 - ruby_on_rails/depfu.md | 6 +- ruby_on_rails/devise.md | 2 +- ruby_on_rails/first_git_push.md | 9 +- ruby_on_rails/linting_and_automatic_check.md | 21 +++- ruby_on_rails/object_storage.md | 2 +- ruby_on_rails/rspec.md | 5 +- ruby_on_rails/sentry.md | 2 +- ruby_on_rails/suggested_libraries.md | 4 +- ruby_on_rails/uptimerobot.md | 2 +- ruby_on_rails/vcr.md | 4 +- ruby_on_rails/wallee.md | 2 +- ruby_on_rails/wicked_pdf.md | 6 +- slack_and_notifications.md | 3 +- sparkpost_and_mailtrap.md | 5 +- templates/README.md | 8 +- 28 files changed, 209 insertions(+), 186 deletions(-) delete mode 100644 ruby_on_rails/compile_readme.md diff --git a/README.md b/README.md index d4a128b6..ec31a19d 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,43 @@ # Renuo Application Setup Guide -This repo is the [Renuo](https://www.renuo.ch) collection of best-practices to set-up apps. +This repo is the [Renuo](https://www.renuo.ch) collection of best-practices to set up apps. We are a [Rails company](https://rubyonrails.org/foundation), so the most value probably will be found in the parts concerning Rails. But anyways you'll also find a lot about the inner workings of Renuo. -* [Ruby on Rails – Application Setup Guide](./ruby_on_rails/README.md) +**You are always welcome to challenge the guide and improve it with a Pull Request.** -## Some Notes on the Side +**Do not blindly follow this guide, always think about what you are doing and why. +If you think something is wrong or simply outdated, improve this guide with a Pull Request.** -If you are reading this document, it means that you have to setup a new application. -A new project started and it's now time to set everything up so that **everyone**, -in your team, **can start working on it**. +## How to Use This Guide -This document will try to be as minimalist as possible and provide you with all the steps to set up the application as -fast as possible. There are things, in Renuo projects, which are mandatory, other that are suggested. -This guide is the result of more than ten years of experience, so this means three things: it's very robust, very opinionated, and possibly very outdated. +The guide is structured as a linear walkthrough. Follow it from top to bottom when setting up a new project. -**You are always welcome to challenge the guide and improve it with a Pull Request.** +1. **Before You Start** — Read [Naming Conventions](naming_conventions.md), [GitFlow](gitflow.md), and [Security](security.md) to understand the ground rules. +2. **Rails Application Setup** — Follow the [step-by-step setup](ruby_on_rails/README.md) to create, deploy, and configure your app. +3. **Guides & Recipes** — Pick the ones you need (emails, authentication, payment, etc.). +4. **Reference** — Use the [Checklist](checklist.md) to verify you haven't missed anything, and the [Go Live!](go_live.md) page when you're ready to launch. -The basic things that need to be ready before the team can start working on a project are: +## What Needs to Be Ready -* An existing *git* repository containing the project -* Two branches: *main* and *develop* +Before the team can start working on a project, you need: + +* A git repository containing the project +* Two branches: *main* and *develop* (or just *main* for internal projects) * A README with essential information about the application -* Convenience-scripts: `bin/setup`, `bin/check`, `bin/fastcheck`, `bin/run` +* Convenience scripts: `bin/setup`, `bin/check`, `bin/fastcheck`, `bin/run` * One running, green test -* Continuous integration (*CI*) ready, running and green for both branches -* Continuous deployment (*CD*) ready and running for both branches -* The application deployed for both branches - -As an appendix, you'll find a [checklist](checklist.md) you can use to follow the guide. - -**:exclamation: Do not blindly follow this guide, always think about what you are doing and why. -If you think something is wrong or simply outdated, improve this guide with a Pull Request.** - -We want you to know exactly the reason behind each single step of this guide. - -Thank you for your work and have fun! :tada: +* CI ready, running and green for all branches +* CD ready and running for all branches +* The application deployed for all branches ## Serving the Documentation Locally To view this documentation on your machine, run the following command: ```sh -mbook serve +mdbook serve ``` ## License diff --git a/SUMMARY.md b/SUMMARY.md index 9690106e..ebe44feb 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -2,65 +2,69 @@ [Overview](README.md) -# General +# Before You Start -- [Create a Git Repository](create_git_repository.md) -- [GitFlow](gitflow.md) -- [Go Live!](go_live.md) - [Naming Conventions](naming_conventions.md) +- [GitFlow](gitflow.md) - [Security](security.md) -- [Project Checklist](checklist.md) -# Rails Application Setup Guide +# Rails Application Setup -- [Getting started](ruby_on_rails/README.md) +- [Getting Started](ruby_on_rails/README.md) -- [Setup]() +- [Step 1: Create the App]() - [Initialise the Rails App](ruby_on_rails/app_initialisation.md) + - [Create a GitHub Repository](create_git_repository.md) - [Push to Git Repository](ruby_on_rails/first_git_push.md) - [Initialise Gitflow](ruby_on_rails/initialise_gitflow.md) - [Configure Git Repository](configure_git_repository.md) - - [Create an Application Server (Heroku)](ruby_on_rails/create_application_server_heroku.md) +- [Step 2: Deploy the App]() - [Create an Application Server (Deploio)](ruby_on_rails/create_application_server_deploio.md) + - [Create an Application Server (Heroku)](ruby_on_rails/create_application_server_heroku.md) - [Configure the CI/CD](ruby_on_rails/configure_ci.md) -- [Tools]() +- [Step 3: Quality Tools]() - [RSpec](ruby_on_rails/rspec.md) - [Linting and automatic checks](ruby_on_rails/linting_and_automatic_check.md) - [Gems and libraries](ruby_on_rails/suggested_libraries.md) - [Cloudflare](ruby_on_rails/cloudflare.md) -- [Additional Services]() +- [Step 4: Monitoring & Protection]() + - [AppSignal](ruby_on_rails/appsignal.md) - [Sentry](ruby_on_rails/sentry.md) - [NewRelic](ruby_on_rails/newrelic.md) - [Robots.txt](ruby_on_rails/robots_txt.md) - [Percy](ruby_on_rails/configure_percy.md) - [Protect develop environment](ruby_on_rails/environment_protection.md) -- [Customer Plan Services]() +- [Step 5: Customer Plan Services]() - [Uptimerobot](ruby_on_rails/uptimerobot.md) - [Depfu Security monitoring](ruby_on_rails/depfu.md) -- [Gems]() - - [Jest](ruby_on_rails/jest.md) - - [Send Emails](ruby_on_rails/send_emails.md) - - [Sparkpost & Mailtrap](sparkpost_and_mailtrap.md) - - [Devise](ruby_on_rails/devise.md) - - [Cucumber](ruby_on_rails/cucumber.md) - - [Object Storage](ruby_on_rails/object_storage.md) - - [Bootstrap](ruby_on_rails/bootstrap.md) - - [FontAwesome](ruby_on_rails/font_awesome.md) - - [Bullet](ruby_on_rails/bullet.md) - - [Lograge](ruby_on_rails/appsignal.md) - - [Hotjar](ruby_on_rails/hotjar.md) - - [Wicked PDF](ruby_on_rails/wicked_pdf.md) - - [Recaptcha v3](ruby_on_rails/recaptcha.md) +# Guides & Recipes + +- [Send Emails](ruby_on_rails/send_emails.md) +- [Sparkpost & Mailtrap](sparkpost_and_mailtrap.md) +- [Devise](ruby_on_rails/devise.md) +- [Object Storage](ruby_on_rails/object_storage.md) +- [Jest](ruby_on_rails/jest.md) +- [Cucumber](ruby_on_rails/cucumber.md) +- [Bootstrap](ruby_on_rails/bootstrap.md) +- [FontAwesome](ruby_on_rails/font_awesome.md) +- [Bullet](ruby_on_rails/bullet.md) +- [Hotjar](ruby_on_rails/hotjar.md) +- [Wicked PDF](ruby_on_rails/wicked_pdf.md) +- [Recaptcha v3](ruby_on_rails/recaptcha.md) +- [Wallee Payment](ruby_on_rails/wallee.md) +- [Content Security Policy](ruby_on_rails/content_security_policy.md) +- [I18n](i18n.md) # Services - [Google Analytics](google_analytics.md) -- [Google Apis](google_apis.md) +- [Google APIs](google_apis.md) - [Slack and Notifications](slack_and_notifications.md) +# Reference -# Templates - -- [README](templates/README.md) +- [Project Checklist](checklist.md) +- [Go Live!](go_live.md) +- [README Template](templates/README.md) - [Pull Request Template](templates/pull_requests_template.md) diff --git a/configure_git_repository.md b/configure_git_repository.md index 373731d9..06b689da 100644 --- a/configure_git_repository.md +++ b/configure_git_repository.md @@ -7,38 +7,37 @@ Please stick to it unless you have special needs. * Features: Remove *Wikis*, *Issues* and *Projects* * Pull Requests * Disable *Allow merge commits* and *Allow rebase merging* - * Always suggest updating pull request branches * Allow auto-merge * Automatically delete head branches + * Always suggest updating pull request branches * Manage access * Add *staff* team as a collaborator with Admin access * Add *security* team as collaborator with Write access * Branches * Default branch: either `main` or `develop` depending on whether you want one or two environments. * Rules/Rulesets - * `develop` + * We use two rulesets: one for `main` and one for everything else. This ensures that long-lived branches like `redesign` and feature branches like `feat/my-feature` share the same protection rules as `develop`. + * `non-main` * Enforcement status: `Active` + * Branch targeting criteria: + * Include all branches + * Exclude by pattern: `main` * Bypass list: add `Repository Admin` Role with *allow for pull requests only* option - * Branch targeting criteria: `develop` * Restrict deletions * Require linear history * Require a pull request before merging * Require status checks to pass - * Select `ci/semaphore/push` (AFTER SETTING UP SEMAPHORE) + * Select `ci/semaphore/push` * Block force pushes - * `main` (same as develop but...) + * `main` (same as non-main but...) * Branch targeting criteria: `main` * ❌ Require a pull request before merging * ❌ Require status checks to pass - * Autolink references * Add a new Autolink reference with: * Reference prefix: `TICKET-` * Target URL: `https://redmine.renuo.ch/issues/` -In case you have a second long-living environment (e.g., for a design rewrite, a new major version, etc.), -consider applying the same rules as on `develop` to it as well. - ## Team Each project has a team owning it. The team is named after the project: `[team-name] = [project-name]`. diff --git a/create_git_repository.md b/create_git_repository.md index ac9dec07..9b1584d1 100644 --- a/create_git_repository.md +++ b/create_git_repository.md @@ -1,4 +1,4 @@ -# Create a Git Repository +# Create a GitHub Repository At Renuo we currently use [GitHub](https://github.com/) as our git repository. You should already be part of the Renuo Organisation and have permissions to do so. If that's not the case, double check the Laptop Setup Guide or ask wg-operations. diff --git a/google_analytics.md b/google_analytics.md index 1a30b7d8..b3b90d6e 100644 --- a/google_analytics.md +++ b/google_analytics.md @@ -33,7 +33,7 @@ script which you can find [here](https://developers.google.com/analytics/devguid Make sure you insert this script at the end of the `` tag of the page (not in the ``). -NOTE: There is a default IP anonymization feature in GA4. We no longer need to perform this step manually. +> **Note:** There is a default IP anonymization feature in GA4. We no longer need to perform this step manually. ## b) Ruby rack-tracker diff --git a/naming_conventions.md b/naming_conventions.md index 26fd5cc0..78ee8283 100644 --- a/naming_conventions.md +++ b/naming_conventions.md @@ -18,7 +18,7 @@ asked to do the same. * Use `[project-name]-[purpose]-[branch]` for deployed projects (e.g. one11-web-main). * Use `[project-name]-local-[user]-[rails_env]` for local names which interact with online services (e.g. S3). -**Note:** Previously on Heroku, the convention was to use `[project-name]-[branch]-[purpose]` for deployed projects (e.g. kingschair-main-assets). This has been updated due to deplo.io. +> **Note:** Previously on Heroku, the convention was to use `[project-name]-[branch]-[purpose]` for deployed projects (e.g. kingschair-main-assets). This has been updated due to deplo.io. ## Examples @@ -32,13 +32,13 @@ asked to do the same. The naming conventions should be applied everywhere. Some examples: -* Amazon S3 (usually [project-name]-[branch]) -* Github ([project-name]) -* Heroku ([project-name]-[branch]) -* Redmine ([project-name]) -* Semaphore CI (servers are named [project-name]-[branch]) -* Drive ([project-name]) -* New Relic ([project-name]-[branch]) +* Amazon S3 (usually `[project-name]-[branch]`) +* Github (`[project-name]`) +* Heroku (`[project-name]-[branch]`) +* Redmine (`[project-name]`) +* Semaphore CI (servers are named `[project-name]-[branch]`) +* Drive (`[project-name]`) +* New Relic (`[project-name]-[branch]`) * Get Sentry * App name in Rails * Sparkpost Account diff --git a/ruby_on_rails/README.md b/ruby_on_rails/README.md index fba970f3..e3dabdc6 100644 --- a/ruby_on_rails/README.md +++ b/ruby_on_rails/README.md @@ -1,39 +1,48 @@ # Ruby On Rails - Application Setup Guide -This setup will cover a pure, monolithic Rails Applications. -This is the most frequent type of application we have at [Renuo](https://renuo.ch) and is probably also the easiest to setup. -The application (and relative GitHub repo) will be named after the `[project-name]` you chose before. +This setup covers a pure, monolithic Rails application. +This is the most frequent type of application at [Renuo](https://renuo.ch) and is probably the easiest to set up. +The application (and its GitHub repo) will be named after the `[project-name]` you chose before. -> [!NOTE] -> Have you chosen a `[project-name]` yet? If not, please do so now. Check our [Naming Conventions](../naming_conventions.md) +> **Note:** Have you chosen a `[project-name]` yet? If not, please do so now. Check our [Naming Conventions](../naming_conventions.md) -> [!NOTE] -> Have you decided if you need two environments (develop and main) or just one? +> **Note:** Have you decided if you need two environments (develop and main) or just one? > As a rule of thumb: for customers we always use two environments, for internal projects we usually only use one. -> Why the difference? Because we can bare the risk of having a bug in an internal project, but we cannot do that for a customer. +> Why the difference? Because we can bear the risk of having a bug in an internal project, but we cannot do that for a customer. > Decide with your team if you want one or two branches. +> :bulb: **Tip:** Sections marked with ✨ are already set up by the Renuo Rails template or ship with Rails 8.1 by default. You only need to verify them, not install them. + +--- + +## Step 1: Create the App + 1. [Initialise the Rails Application](app_initialisation.md) 1. [Push to Git Repository](first_git_push.md) 1. [Initialise Gitflow](initialise_gitflow.md) -1. [Configure Github Repository](../configure_git_repository.md) +1. [Configure GitHub Repository](../configure_git_repository.md) + +## Step 2: Deploy the App + 1. [Create an Application Server for Deploio](create_application_server_deploio.md) or [Create an Application Server for Heroku](create_application_server_heroku.md) -1. [Configure the CI / CD](configure_ci.md) +1. [Configure the CI/CD](configure_ci.md) + +Your app should now be up and running on all environments. -Once here, your app should be up and running on all environments. +## Step 3: Quality Tools -It's now time to introduce some more tools which will help you and the team to keep a high quality during the project development. +Set up the tools that help your team maintain high quality throughout development. 1. [RSpec](rspec.md) 1. [Linting and automatic checks](linting_and_automatic_check.md) -1. [Gems and libraries :gem:](suggested_libraries.md) +1. [Gems and libraries](suggested_libraries.md) 1. [Cloudflare](cloudflare.md) -1. [README](compile_readme.md) -:tada: Finally you are ready to start working on you new project! :tada: +Your team can now start working on the project. -While everyone starts working there are some more things which you should setup. -Most are not optional, but the rest of the team can start working even if those are not in place yet. +## Step 4: Monitoring & Protection + +Set these up while the rest of the team starts working. Most are not optional, but they don't block other work. 1. [AppSignal](appsignal.md) 1. [Sentry](sentry.md) (optional) @@ -42,40 +51,44 @@ Most are not optional, but the rest of the team can start working even if those 1. [Percy](configure_percy.md) (optional) 1. [Protect develop environment](environment_protection.md) -Some services should be configured accordingly to the packages bought by the customer. -Once the new application is created, please add the project to the +## Step 5: Customer Plan Services + +Once the application is created, add the project to the [monitoring list](https://docs.google.com/spreadsheets/d/1FY4jqByO-aI5sDan0hD7ULu6a2-eLsmO6kgdCFlPmuY/edit#gid=0) -and discuss with the PO how the service should be configured. +and discuss with the PO how the services should be configured. 1. [Uptimerobot](uptimerobot.md) 1. Depending on the monitoring list, also [Sentry notifications](sentry.md) need to be configured. 1. [Depfu security monitoring](depfu.md) 1. Depending on the monitoring list, also [Papertrail alerts](papertrail.md) need to be configured. -Here you will find a series of chapters and guides on how to setup some of the gems we use most often and some other -useful services: - -1. [Run Javascript tests with Jest](jest.md) -1. [Pull Requests Template](../pull_requests_template.md) -1. [Slack and Project Notifications](../slack_and_notifications.md) -1. [Send emails](send_emails.md) -1. [Sparkpost & Mailtrap](../sparkpost_and_mailtrap.md) -1. [Devise](devise.md) -1. [Cucumber](cucumber.md) -1. [Object storage](object_storage.md) -1. awesome_print `gem 'awesome_print'` -1. [bootstrap](bootstrap.md) -1. [font-awesome](font_awesome.md) -1. [bullet](bullet.md) `gem 'bullet'` -1. [lograge](appsignal.md) `gem 'lograge'` -1. Rack Tracker (Google Analytics) `gem 'rack-tracker'` --> see [Google Analytics](../google_analytics.md) -1. Favicons -1. [Rack CORS](https://github.com/cyu/rack-cors) -1. [Rack Attack](https://github.com/rack/rack-attack#installing) -1. [:fire: Hotjar](hotjar.md) -1. SEO - * redirect non-www to www - * Header tags -1. [wicked pdf](wicked_pdf.md) `gem wicked_pdf` -1. [Recaptcha v3](recaptcha.md) -1. [Wallee Payment Integration](wallee.md) +--- + +## Guides & Recipes + +The following are not part of the sequential setup. Use them as needed for your project. + +* [Run JavaScript tests with Jest](jest.md) +* [Pull Requests Template](../templates/pull_requests_template.md) +* [Slack and Project Notifications](../slack_and_notifications.md) +* [Send emails](send_emails.md) +* [Sparkpost & Mailtrap](../sparkpost_and_mailtrap.md) +* [Devise](devise.md) +* [Cucumber](cucumber.md) +* [Object storage](object_storage.md) +* awesome_print `gem 'awesome_print'` +* [Bootstrap](bootstrap.md) +* [FontAwesome](font_awesome.md) +* [Bullet](bullet.md) `gem 'bullet'` +* [Lograge](appsignal.md#lograge) `gem 'lograge'` +* Rack Tracker (Google Analytics) `gem 'rack-tracker'` → see [Google Analytics](../google_analytics.md) +* Favicons +* [Rack CORS](https://github.com/cyu/rack-cors) +* [Rack Attack](https://github.com/rack/rack-attack#installing) +* [Hotjar](hotjar.md) +* SEO + * redirect non-www to www + * Header tags +* [Wicked PDF](wicked_pdf.md) `gem wicked_pdf` +* [Recaptcha v3](recaptcha.md) +* [Wallee Payment Integration](wallee.md) diff --git a/ruby_on_rails/app_initialisation.md b/ruby_on_rails/app_initialisation.md index c6626749..5c65a77a 100644 --- a/ruby_on_rails/app_initialisation.md +++ b/ruby_on_rails/app_initialisation.md @@ -18,7 +18,7 @@ rails new [project-name] --database=postgresql --skip-kamal --skip-ci --skip-act ``` where the `project-name` is exactly the one you chose before. -> ⚠️ You may want to choose a different database than Postgres, but most of the time this will be your choice.\ +> :warning: You may want to choose a different database than Postgres, but most of the time this will be your choice.\ > You might also need actionmailbox of course, so always double-check the parameters that you are using. > ⭐️ This setup does not include either js-bundling nor css-bundling by default.\ @@ -29,9 +29,9 @@ where the `project-name` is exactly the one you chose before. * Run `bundle exec rails db:migrate` to generate an empty `schema.rb` file. * Run `bin/setup` -* Then check your default Rails setup by running `bin/run` and visiting http://[project-name].localhost:3000. +* Then check your default Rails setup by running `bin/run` and visiting [http://[project-name].localhost:3000](http://[project-name].localhost:3000). You should be on Rails now, yay! -* Finally check if http://localhost:3000/up is green. +* Finally check if [http://localhost:3000/up](http://localhost:3000/up) is green. ## Adjustments @@ -40,31 +40,31 @@ Some other adjustments must be performed manually. ### Automatic adjustments -> ⭐️The `config/database.yml` is updated to have a `collation: C.UTF-8` setting. +> ⭐️ The `config/database.yml` is updated to have a `collation: C.UTF-8` setting. > This ensures deterministic, locale-independent sorting and avoids inconsistencies between local and production > environments. -> ⭐The Gemfile reads the required ruby version from the `.ruby-version` file. +> ⭐️ The Gemfile reads the required ruby version from the `.ruby-version` file. > [This is used by Heroku to determine what version to use.](https://devcenter.heroku.com/articles/ruby-versions) -> Deploio reads the ruby version from the Gemfile, with the .ruby-version file inlined into it. https://paketo.io/docs/howto/ruby/#override-the-detected-ruby-version +> Deploio reads the ruby version from the Gemfile, with the `.ruby-version` file inlined into it. See . -> ⭐️renuocop replaces the default rubocop-rails-omakase. We have our own set of rules at Renuo. -> You can discuss them at https://github.com/renuo/renuocop and you can also contribute to them. +> ⭐️ renuocop replaces the default rubocop-rails-omakase. We have our own set of rules at Renuo. +> You can discuss them at and you can also contribute to them. -> ⭐️a bin/check script is added to the project. This script will run all the tests of the project. +> ⭐️ A `bin/check` script is added to the project. This script will run all the tests of the project. > It is used in our CI and can be used locally to check if everything is fine. You can customize it to your needs. -> ⭐️a bin/fastcheck script is added to the project. +> ⭐️ A `bin/fastcheck` script is added to the project. > This script will run all the linters of the project. It is used in our CI and can be customized to your needs. > It will be used as a hook before pushing to quickly check for linting issues. -> ⭐️a bin/run script is added to the project. This script will start the application. +> ⭐️ A `bin/run` script is added to the project. This script will start the application. -> ⭐️bin/check, bin/fastcheck and bin/run are standardized tools for more convenience at Renuo. +> ⭐️ `bin/check`, `bin/fastcheck` and `bin/run` are standardized tools for more convenience at Renuo. ### Secrets -We store the secrets necessary to configure the project locally in a 1password Item. +We store the secrets necessary to configure the project locally in a 1Password Item. Create a new Item for the project called `[project-name] project secrets` of type note. Right click on the vault and select `Copy Private link`. @@ -78,8 +78,8 @@ Check existing projects for an example of the usage. * Update `config/application.rb` and set the default language and timezone ```ruby - config.time_zone = 'Zurich' - config.i18n.default_locale = :de + config.time_zone = 'Zurich' # may vary + config.i18n.default_locale = :de # may vary ``` * Update your `config/environments/production.rb` settings: @@ -95,7 +95,9 @@ Check existing projects for an example of the usage. config.action_controller.action_on_unpermitted_parameters = :raise config.i18n.raise_on_missing_translations = :strict - config.generators.apply_rubocop_autocorrect_after_generate! + config.generators do |g| + g.apply_rubocop_autocorrect_after_generate! + end ``` * Update `config/environments/test.rb` settings: @@ -129,4 +131,4 @@ Check existing projects for an example of the usage. ## Finalising * Check if the following scripts run successfully: `bin/setup`, `bin/check`, `bin/run` -* If they do, commit all your changes to the main branch with Git. +* If they do, you're ready for the next step. diff --git a/ruby_on_rails/compile_readme.md b/ruby_on_rails/compile_readme.md deleted file mode 100644 index 8017a7e2..00000000 --- a/ruby_on_rails/compile_readme.md +++ /dev/null @@ -1,4 +0,0 @@ -# README File - -It's time to compile our README.md file for the project. -Please follow the [README](../templates/README.md). \ No newline at end of file diff --git a/ruby_on_rails/configure_ci.md b/ruby_on_rails/configure_ci.md index b3e34778..f0faa154 100644 --- a/ruby_on_rails/configure_ci.md +++ b/ruby_on_rails/configure_ci.md @@ -4,13 +4,13 @@ At Renuo we **always** use a CI (Continuous Integration) system to test our appl that all the tests pass before building and releasing a new version through our CD system. Our projects use [SemaphoreCI](). -ℹ️ _Are you using **Gitlab**? Have a look at [this example](./gitlab_capybara_selenium.md) instead (and elaborate)._ +> _Are you using **Gitlab**? Have a look at [this example](./gitlab_capybara_selenium.md) instead (and elaborate)._ Before configuring the CI, you should already have a Git Repository with the code, a `bin/check` command to execute, and the main branches already pushed and ready to be tested. 1. Proceed to and login through GitHub with renuobot@renuo.ch ([1Password](https://start.1password.com/open/i?a=QZNJJCCDWVCGBGI73Z2L55KSGE&v=crlutt26yprmp6thr573qxsxkq&i=u7rirvnrf5fjxd25caiq7ib6vq&h=renuo.1password.com)) -1. Follow these instructions to install semaphore CLI https://docs.semaphoreci.com/reference/sem-command-line-tool/ +1. Follow these instructions to install semaphore CLI: 1. Create a project here: 1. Go to the project's artifact settings: `Settings` > `Artifacts` 1. Set the retention policy for project, workflow and job artifacts to `/**/*` and `2 weeks` diff --git a/ruby_on_rails/content_security_policy.md b/ruby_on_rails/content_security_policy.md index 5b07ee31..ee106c46 100644 --- a/ruby_on_rails/content_security_policy.md +++ b/ruby_on_rails/content_security_policy.md @@ -85,7 +85,7 @@ Starting from Rails 6 on, the `javascript_tag` view helper also accepts a nonce | img-src | `https://www.google-analytics.com` | | connect-src | `https://www.google-analytics.com` | -For a more details list, see https://developers.google.com/tag-manager/web/csp +For a more details list, see . ### Facebook Tracking Pixel diff --git a/ruby_on_rails/create_application_server_deploio.md b/ruby_on_rails/create_application_server_deploio.md index 1a20eeff..8c1a9703 100644 --- a/ruby_on_rails/create_application_server_deploio.md +++ b/ruby_on_rails/create_application_server_deploio.md @@ -8,8 +8,8 @@ Before setting up your application, ensure you have completed the following for - You've [read about what Deploio is](https://docs.nine.ch/docs/deplo-io/getting-started-with-deploio). - You have a Deploio account. -- You have installed the `renuo-cli` gem. -- You have installed the `nctl` command. +- You have installed the [`renuo-cli`](https://github.com/renuo/renuo-cli) gem. +- You have installed the [`nctl`](https://github.com/ninech/nctl) command. - You have logged in using `nctl`. ## Setup Your Application @@ -24,7 +24,10 @@ Run [the command to generate a script](https://github.com/renuo/renuo-cli/blob/m renuo create-deploio-app [project-name] [git-url] ``` -e.g. `renuo create-deploio-app my-app git@github.com:renuo/my-app.git` +e.g: +```sh +renuo create-deploio-app my-app git@github.com:renuo/my-app.git +``` Please review the script before running it and execute only the commands you need and understand. In particular, you might need only one of the two environments if you decided to not use `develop`. @@ -36,7 +39,7 @@ If you think that the production database will soon reach the 10 GB, please cons If you think that the script is outdated, please open a Pull Request on the [renuo-cli](https://github.com/renuo/renuo-cli) project. -For further configuration and best practices, please refer to the [Deploio documentation](https://guides.deplo.io). You can also view a Ruby on Rails specific guide [here](https://guides.deplo.io/ruby/quick-start.html). +For further configuration, see the [Rails on Deploio guide](https://guides.deplo.io/ruby/quick-start.html). For general Deploio docs, see [guides.deplo.io](https://guides.deplo.io). ## Next Steps diff --git a/ruby_on_rails/cucumber.md b/ruby_on_rails/cucumber.md index 1beba008..7f353006 100644 --- a/ruby_on_rails/cucumber.md +++ b/ruby_on_rails/cucumber.md @@ -41,8 +41,6 @@ If you add Cucumber to an existing project, test a real page instead of using th Add the following files: -* [`app/controllers/home_controller.rb`](../templates/app/controllers/home_controller.rb) (If you haven't done so -already) in the [RSpec](rspec.md) section. * [`features/home_check.feature`](../templates/features/home_check.feature) * [`features/step_definitions/home_check_steps.rb`](../templates/features/step_definitions/home_check_steps.rb) diff --git a/ruby_on_rails/depfu.md b/ruby_on_rails/depfu.md index 1986dac9..acdfc78b 100644 --- a/ruby_on_rails/depfu.md +++ b/ruby_on_rails/depfu.md @@ -17,9 +17,9 @@ Enable minor engine updates. ![Depfu Engine Updates](../images/depfu_engine_updates.png) -**Note:** If you are using Heroku, the latest Ruby / node version may not yet -be available on their platform, so you may need to delay the upgrade. Check the -following GitHub repositories to see if Heroku added support already: +> **Note:** If you are using Heroku, the latest Ruby / node version may not yet +> be available on their platform, so you may need to delay the upgrade. Check the +> following GitHub repositories to see if Heroku added support already: - - diff --git a/ruby_on_rails/devise.md b/ruby_on_rails/devise.md index 7954e3bf..216e3103 100644 --- a/ruby_on_rails/devise.md +++ b/ruby_on_rails/devise.md @@ -1,6 +1,6 @@ # Devise -:warning: If you are going to use devise we suggest you to [send_emails](send_emails.md) first. :warning: +> :warning: If you are going to use devise we suggest you to [send_emails](send_emails.md) first. * Add the following gem `gem 'devise'` and install it diff --git a/ruby_on_rails/first_git_push.md b/ruby_on_rails/first_git_push.md index 28136a46..c5c1f824 100644 --- a/ruby_on_rails/first_git_push.md +++ b/ruby_on_rails/first_git_push.md @@ -1,18 +1,15 @@ # Push to Git Repository -It's now time to push to the git repository and configure our CI and CD to deploy our application on Heroku. -To do that you first need to [Create a Git Repository](../create_git_repository.md). +By now `rails new` has already initialised the local git repository and created an initial commit for you. This step pushes that commit to the GitHub repository you created in the [previous step](../create_git_repository.md). -After creating the repo you can connect your project to the remote git repo (if you didn't use `hub create` command) +If you used `hub create -p renuo/[project-name]`, the `origin` remote is already set. Otherwise, add it: ```sh git remote add origin git@github.com:renuo/[project-name].git ``` -and push using: +Then push: ```sh -git add . -git commit -m "Initial commit" git push -u origin main ``` diff --git a/ruby_on_rails/linting_and_automatic_check.md b/ruby_on_rails/linting_and_automatic_check.md index 987e850a..5bbd94d9 100644 --- a/ruby_on_rails/linting_and_automatic_check.md +++ b/ruby_on_rails/linting_and_automatic_check.md @@ -7,8 +7,9 @@ Check out the `bin/fastcheck` [fastcheck](../templates/bin/fastcheck) for the fi ## Renuocop :cop: +> ✨ Installed by the Renuo Rails template (replaces `rubocop-rails-omakase`). + Renuocop is based on Standard Ruby and is a set of rules that we use to lint our Ruby code. -It's already included in your Gemfile by default. You can execute it and correct the issues you'll find. @@ -16,12 +17,26 @@ You can execute it and correct the issues you'll find. ## Brakeman -Brakeman comes by default with Rails. Add it to the `bin/fastcheck` script. +> ✨ Ships with Rails 8.1 by default. + +Add it to the `bin/fastcheck` script: ```sh bundle exec brakeman -q -z --no-summary --no-pager ``` +## Bundler-audit + +> ✨ Ships with Rails 8.1 by default. + +Scans `Gemfile.lock` for gems with known security vulnerabilities. Add it to the `bin/fastcheck` script: + +```sh +bundle exec bundler-audit check --update +``` + +Use `config/bundler-audit.yml` to ignore specific advisories if needed. + ## Mdl An optional check for markdown files. You can include it or not. Discuss within your team. @@ -34,7 +49,7 @@ end ## SCSS lint -> _Note_: Your Semaphore configuration might have to be adjusted if you decide to use `npm`. +> **Note:** Your Semaphore configuration might have to be adjusted if you decide to use `npm`. To lint the SASS/SCSS files in our project you can use the `stylelint` npm package. diff --git a/ruby_on_rails/object_storage.md b/ruby_on_rails/object_storage.md index 728d325a..b68268cf 100644 --- a/ruby_on_rails/object_storage.md +++ b/ruby_on_rails/object_storage.md @@ -51,7 +51,7 @@ The following Amazon services are involved in our app setups You will need Renuo-CLI to be set up and at the newest version: -`gem install renuo-cli` --> see [renuo-cli](https://github.com/renuo/renuo-cli) +`gem install renuo-cli` → see [renuo-cli](https://github.com/renuo/renuo-cli) Make sure `renuo -v` shows the [newest version](https://github.com/renuo/renuo-cli/tags) diff --git a/ruby_on_rails/rspec.md b/ruby_on_rails/rspec.md index 7499fe64..edff21c6 100644 --- a/ruby_on_rails/rspec.md +++ b/ruby_on_rails/rspec.md @@ -1,5 +1,8 @@ # Setup RSpec +> **Note:** The Renuo Rails template does NOT set up RSpec. All steps on this page are manual. +> Rails 8.1 does ship `capybara` and `selenium-webdriver` in the `:test` group by default. There is no need to add those manually when using the template. + Even though Rails uses Minitest per default, RSpec is the *de-facto* standard at Renuo. Add the following gems to your Gemfile: @@ -156,7 +159,7 @@ end * Add the line `bundle exec parallel_rspec` to `bin/check` -> **Note**: If you want to debug a spec, you can simply uncomment the line `SELENIUM_DRIVER` in the .env to not run it headless: +> **Note:** If you want to debug a spec, you can simply uncomment the line `SELENIUM_DRIVER` in the .env to not run it headless: ![CleanShot 2021-06-25 at 16 54 22](https://user-images.githubusercontent.com/1319150/123443347-1bbcae80-d5d6-11eb-8ba5-0d2c9ae4a37c.gif) diff --git a/ruby_on_rails/sentry.md b/ruby_on_rails/sentry.md index 97fa88a9..10eb86aa 100644 --- a/ruby_on_rails/sentry.md +++ b/ruby_on_rails/sentry.md @@ -2,7 +2,7 @@ ## General configuration -* Go to https://www.sentry.io and login as the renuo monitor user. +* Go to and login as the renuo monitor user. * Create a project named `[project-name]`. diff --git a/ruby_on_rails/suggested_libraries.md b/ruby_on_rails/suggested_libraries.md index 256a5d93..6cad8d0e 100644 --- a/ruby_on_rails/suggested_libraries.md +++ b/ruby_on_rails/suggested_libraries.md @@ -5,7 +5,7 @@ Please include them or find a good reason not to. > :exclamation: Please follow the guide of each of these libraries to know how to properly install them. -> **:bulb:** Do you know all of them? Do you know why we'd like them to be included? +> :bulb: **Tip:** Do you know all of them? Do you know why we'd like them to be included? ```rb gem 'simple_form' @@ -25,4 +25,4 @@ group :production do end ``` -> **:bulb:** Note that to install `simple_form` you need to run `rails generate simple_form:install --bootstrap` (without option if not using Bootstrap) after adding it to your Gemfile. +> :bulb: **Tip:** To install `simple_form`, run `rails generate simple_form:install --bootstrap` (omit the option if not using Bootstrap) after adding it to your Gemfile. diff --git a/ruby_on_rails/uptimerobot.md b/ruby_on_rails/uptimerobot.md index 2fbb27ed..3660d187 100644 --- a/ruby_on_rails/uptimerobot.md +++ b/ruby_on_rails/uptimerobot.md @@ -11,7 +11,7 @@ dyno. ## Setup You will need Renuo-CLI to be set up and at the newest version: -`gem install renuo-cli` --> see [renuo-cli](https://github.com/renuo/renuo-cli) +`gem install renuo-cli` → see [renuo-cli](https://github.com/renuo/renuo-cli) 1. Run the command `renuo setup-uptimerobot [url]` * Where `url` is the address you want to monitor. e.g. `https://[project-name]-main.renuoapp.ch/up` or `https://customdomain.ch/up` diff --git a/ruby_on_rails/vcr.md b/ruby_on_rails/vcr.md index e727f26b..c762ebc2 100644 --- a/ruby_on_rails/vcr.md +++ b/ruby_on_rails/vcr.md @@ -46,9 +46,9 @@ end ``` Some considerations: -* Do you really want/need VCR? A fake may be better: https://thoughtbot.com/blog/how-to-stub-external-services-in-tests#create-a-fake-hello-sinatra +* Do you really want/need VCR? A fake may be better: * Do you test so specifically that WebMock would be the better tool? -* Does your project have special needs for tweaks: https://blog.arkency.com/3-tips-to-tune-your-vcr-in-tests/ +* Does your project have special needs for tweaks: * How often do you want to re-record your cassettes? Out-of-date replays may give you a false sense of safety. * Where do you want to re-record your cassettes? Maybe nightly on the CI? diff --git a/ruby_on_rails/wallee.md b/ruby_on_rails/wallee.md index b4eec435..c1c83146 100644 --- a/ruby_on_rails/wallee.md +++ b/ruby_on_rails/wallee.md @@ -273,7 +273,7 @@ Be aware that this is quite integrated with the business logic of your app, e.g. let(:wallee_transaction_id) { "194681414" } - it "goes the 😊 path" do + it "goes the happy path" do create(:shop_order, wallee_transaction_id: wallee_transaction_id) post wallee_webhook_path, env: {"HTTP_X_SIGNATURE" => "fake"}, diff --git a/ruby_on_rails/wicked_pdf.md b/ruby_on_rails/wicked_pdf.md index 4c34f6f7..f017b99f 100644 --- a/ruby_on_rails/wicked_pdf.md +++ b/ruby_on_rails/wicked_pdf.md @@ -2,7 +2,7 @@ Can be used to generate PDFs and supports HTML to PDF. -:warning: Up to now, Wicked PDF does not support Bootstrap 4, so if you want to use Bootstrap 4 Templates, use another library :warning: +> :warning: Up to now, Wicked PDF does not support Bootstrap 4, so if you want to use Bootstrap 4 Templates, use another library. * Add `gem 'wicked_pdf'` to the main section of `Gemfile` * Add `gem 'wkhtmltopdf-binary'` to `group :development, :test` @@ -20,7 +20,7 @@ By default, it adds no layout, you you may want to add a layout: render pdf: <>, print_media_type: true, layout: 'pdf', disposition: 'attachment' ``` -:warning: Consider using a job-runner to not block the server during creation of PDFs. +> :warning: Consider using a job-runner to not block the server during creation of PDFs. ## Heroku @@ -29,4 +29,4 @@ If you need Arial, you can add the following buildpack on Heroku: `https://github.com/propertybase/heroku-buildpack-fonts` -:warning: Make sure you add this as a first buildpack before `heroku/ruby`! +> :warning: Make sure you add this as a first buildpack before `heroku/ruby`! diff --git a/slack_and_notifications.md b/slack_and_notifications.md index b562c025..a2590526 100644 --- a/slack_and_notifications.md +++ b/slack_and_notifications.md @@ -18,7 +18,8 @@ One notification you may want to receive on this channel is about when a new dep order to do that you must be an admin of the Renuo Slack Organisation. If you are not an admin, ask wg-operations to do it for you communicating the `[project-name]`. -:warning: **You must have already setup [Automatic Deployment through SemaphoreCI](ruby_on_rails/configure_ci.md)** :warning: +> :warning: **You must have already setup [Automatic Deployment through SemaphoreCI](ruby_on_rails/configure_ci.md).** + If you used Renuo CLI to configure SemaphoreCI, the notifications should be already created. For manual setup, follow these steps: 1. Open the global Notifications settings (`https://renuo.semaphoreci.com/notifications`) diff --git a/sparkpost_and_mailtrap.md b/sparkpost_and_mailtrap.md index b36a5d3d..1a55fcbe 100644 --- a/sparkpost_and_mailtrap.md +++ b/sparkpost_and_mailtrap.md @@ -1,6 +1,6 @@ # SparkPost & Mailtrap -⚠️ Always use subaccounts in Sparkpost! +> :warning: Always use subaccounts in Sparkpost! > Otherwise there may be compliance issues which can lead to the closing down of the whole Renuo account. @@ -28,8 +28,7 @@ ## Sparkpost -:warning: -Always use subaccounts for the project, so that the whole account doesn't get suspended / blocked in case of compliance issues! +> :warning: Always use subaccounts for the project, so that the whole account doesn't get suspended / blocked in case of compliance issues! 1. Go to and log in with the credentials for sparkpost+_enviroment_@renuo.ch found in the credential store diff --git a/templates/README.md b/templates/README.md index 7a88d9a6..539e15b6 100644 --- a/templates/README.md +++ b/templates/README.md @@ -4,10 +4,10 @@ Short project description ## Environments -| Branch | Domain | Deployment | -| ------- | ------------------------------------- | ---------------| -| develop | https://`[project-name]`-develop.renuoapp.ch | auto | -| main | https://`[project-name]`-main.renuoapp.ch | release | +| Branch | Domain | Deployment | +| ------- | ------------------------------------------ | ---------------| +| develop | https://[project-name]-develop.renuoapp.ch | auto | +| main | https://[project-name]-main.renuoapp.ch | release | ## Setup From 462f54e7a3ec3a0dbf1f4747760352b16cfce6ae Mon Sep 17 00:00:00 2001 From: Dani Bengl Date: Thu, 30 Apr 2026 11:52:15 +0200 Subject: [PATCH 2/2] Normalize all callouts to GitHub-flavored alert syntax MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Convert every blockquote-style note/warning/tip/important into the GitHub `> [!XXX]` form so the docs render consistently: - `> **Note:**` / `> _Note_:` / `**Note:**` → `> [!NOTE]` - `> ⚠️ ...` / `:warning:`-bracketed callouts → `> [!WARNING]` - `> :exclamation:` / `**:exclamation:` → `> [!IMPORTANT]` - `> :bulb:` → `> [!TIP]` - `> ⭐️` template-provided markers and `> ✨` Rails-default markers (semantically informational) → `> [!NOTE]` - `ℹ️ _..._` → `> [!NOTE]` Decorative emoji in headings, links, and celebratory inline lines (e.g. `:tada:`, `:fire:`, `:gem:`) are out of scope here and live in feature/emoji-cleanup. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 5 +++-- google_analytics.md | 3 ++- naming_conventions.md | 3 ++- ruby_on_rails/README.md | 9 ++++++--- ruby_on_rails/app_initialisation.md | 3 ++- ruby_on_rails/configure_ci.md | 3 ++- ruby_on_rails/depfu.md | 3 ++- ruby_on_rails/devise.md | 3 ++- ruby_on_rails/linting_and_automatic_check.md | 3 ++- ruby_on_rails/rspec.md | 11 +++++++---- ruby_on_rails/suggested_libraries.md | 9 ++++++--- ruby_on_rails/wicked_pdf.md | 9 ++++++--- slack_and_notifications.md | 3 ++- sparkpost_and_mailtrap.md | 8 ++++---- 14 files changed, 48 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index ec31a19d..a07678d3 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,9 @@ inner workings of Renuo. **You are always welcome to challenge the guide and improve it with a Pull Request.** -**Do not blindly follow this guide, always think about what you are doing and why. -If you think something is wrong or simply outdated, improve this guide with a Pull Request.** +> [!IMPORTANT] +> Do not blindly follow this guide, always think about what you are doing and why. +> If you think something is wrong or simply outdated, improve this guide with a Pull Request. ## How to Use This Guide diff --git a/google_analytics.md b/google_analytics.md index b3b90d6e..8cb2c802 100644 --- a/google_analytics.md +++ b/google_analytics.md @@ -33,7 +33,8 @@ script which you can find [here](https://developers.google.com/analytics/devguid Make sure you insert this script at the end of the `` tag of the page (not in the ``). -> **Note:** There is a default IP anonymization feature in GA4. We no longer need to perform this step manually. +> [!NOTE] +> There is a default IP anonymization feature in GA4. We no longer need to perform this step manually. ## b) Ruby rack-tracker diff --git a/naming_conventions.md b/naming_conventions.md index 78ee8283..b2f64ee2 100644 --- a/naming_conventions.md +++ b/naming_conventions.md @@ -18,7 +18,8 @@ asked to do the same. * Use `[project-name]-[purpose]-[branch]` for deployed projects (e.g. one11-web-main). * Use `[project-name]-local-[user]-[rails_env]` for local names which interact with online services (e.g. S3). -> **Note:** Previously on Heroku, the convention was to use `[project-name]-[branch]-[purpose]` for deployed projects (e.g. kingschair-main-assets). This has been updated due to deplo.io. +> [!NOTE] +> Previously on Heroku, the convention was to use `[project-name]-[branch]-[purpose]` for deployed projects (e.g. kingschair-main-assets). This has been updated due to deplo.io. ## Examples diff --git a/ruby_on_rails/README.md b/ruby_on_rails/README.md index e3dabdc6..a44d5704 100644 --- a/ruby_on_rails/README.md +++ b/ruby_on_rails/README.md @@ -4,14 +4,17 @@ This setup covers a pure, monolithic Rails application. This is the most frequent type of application at [Renuo](https://renuo.ch) and is probably the easiest to set up. The application (and its GitHub repo) will be named after the `[project-name]` you chose before. -> **Note:** Have you chosen a `[project-name]` yet? If not, please do so now. Check our [Naming Conventions](../naming_conventions.md) +> [!NOTE] +> Have you chosen a `[project-name]` yet? If not, please do so now. Check our [Naming Conventions](../naming_conventions.md) -> **Note:** Have you decided if you need two environments (develop and main) or just one? +> [!NOTE] +> Have you decided if you need two environments (develop and main) or just one? > As a rule of thumb: for customers we always use two environments, for internal projects we usually only use one. > Why the difference? Because we can bear the risk of having a bug in an internal project, but we cannot do that for a customer. > Decide with your team if you want one or two branches. -> :bulb: **Tip:** Sections marked with ✨ are already set up by the Renuo Rails template or ship with Rails 8.1 by default. You only need to verify them, not install them. +> [!TIP] +> Sections marked with ✨ are already set up by the Renuo Rails template or ship with Rails 8.1 by default. You only need to verify them, not install them. --- diff --git a/ruby_on_rails/app_initialisation.md b/ruby_on_rails/app_initialisation.md index 5c65a77a..9e984adc 100644 --- a/ruby_on_rails/app_initialisation.md +++ b/ruby_on_rails/app_initialisation.md @@ -18,7 +18,8 @@ rails new [project-name] --database=postgresql --skip-kamal --skip-ci --skip-act ``` where the `project-name` is exactly the one you chose before. -> :warning: You may want to choose a different database than Postgres, but most of the time this will be your choice.\ +> [!WARNING] +> You may want to choose a different database than Postgres, but most of the time this will be your choice. > You might also need actionmailbox of course, so always double-check the parameters that you are using. > ⭐️ This setup does not include either js-bundling nor css-bundling by default.\ diff --git a/ruby_on_rails/configure_ci.md b/ruby_on_rails/configure_ci.md index f0faa154..65ec7c10 100644 --- a/ruby_on_rails/configure_ci.md +++ b/ruby_on_rails/configure_ci.md @@ -4,7 +4,8 @@ At Renuo we **always** use a CI (Continuous Integration) system to test our appl that all the tests pass before building and releasing a new version through our CD system. Our projects use [SemaphoreCI](). -> _Are you using **Gitlab**? Have a look at [this example](./gitlab_capybara_selenium.md) instead (and elaborate)._ +> [!NOTE] +> Are you using **Gitlab**? Have a look at [this example](./gitlab_capybara_selenium.md) instead (and elaborate). Before configuring the CI, you should already have a Git Repository with the code, a `bin/check` command to execute, and the main branches already pushed and ready to be tested. diff --git a/ruby_on_rails/depfu.md b/ruby_on_rails/depfu.md index acdfc78b..8b55e7c9 100644 --- a/ruby_on_rails/depfu.md +++ b/ruby_on_rails/depfu.md @@ -17,7 +17,8 @@ Enable minor engine updates. ![Depfu Engine Updates](../images/depfu_engine_updates.png) -> **Note:** If you are using Heroku, the latest Ruby / node version may not yet +> [!NOTE] +> If you are using Heroku, the latest Ruby / node version may not yet > be available on their platform, so you may need to delay the upgrade. Check the > following GitHub repositories to see if Heroku added support already: diff --git a/ruby_on_rails/devise.md b/ruby_on_rails/devise.md index 216e3103..013cbe98 100644 --- a/ruby_on_rails/devise.md +++ b/ruby_on_rails/devise.md @@ -1,6 +1,7 @@ # Devise -> :warning: If you are going to use devise we suggest you to [send_emails](send_emails.md) first. +> [!WARNING] +> If you are going to use devise we suggest you to [send_emails](send_emails.md) first. * Add the following gem `gem 'devise'` and install it diff --git a/ruby_on_rails/linting_and_automatic_check.md b/ruby_on_rails/linting_and_automatic_check.md index 5bbd94d9..bc94b716 100644 --- a/ruby_on_rails/linting_and_automatic_check.md +++ b/ruby_on_rails/linting_and_automatic_check.md @@ -49,7 +49,8 @@ end ## SCSS lint -> **Note:** Your Semaphore configuration might have to be adjusted if you decide to use `npm`. +> [!NOTE] +> Your Semaphore configuration might have to be adjusted if you decide to use `npm`. To lint the SASS/SCSS files in our project you can use the `stylelint` npm package. diff --git a/ruby_on_rails/rspec.md b/ruby_on_rails/rspec.md index edff21c6..2c8bed04 100644 --- a/ruby_on_rails/rspec.md +++ b/ruby_on_rails/rspec.md @@ -1,6 +1,7 @@ # Setup RSpec -> **Note:** The Renuo Rails template does NOT set up RSpec. All steps on this page are manual. +> [!NOTE] +> The Renuo Rails template does NOT set up RSpec. All steps on this page are manual. > Rails 8.1 does ship `capybara` and `selenium-webdriver` in the `:test` group by default. There is no need to add those manually when using the template. Even though Rails uses Minitest per default, RSpec is the *de-facto* standard at Renuo. @@ -159,7 +160,8 @@ end * Add the line `bundle exec parallel_rspec` to `bin/check` -> **Note:** If you want to debug a spec, you can simply uncomment the line `SELENIUM_DRIVER` in the .env to not run it headless: +> [!NOTE] +> If you want to debug a spec, you can simply uncomment the line `SELENIUM_DRIVER` in the .env to not run it headless: ![CleanShot 2021-06-25 at 16 54 22](https://user-images.githubusercontent.com/1319150/123443347-1bbcae80-d5d6-11eb-8ba5-0d2c9ae4a37c.gif) @@ -173,8 +175,9 @@ We are now going to write a first test to ensure that the whole configuration is Commit and push your changes! :tada: -> ⭐️ The default health check path for Rails is `/up`. [Learn more in the Rails guides](https://edgeapi.rubyonrails.org/classes/Rails/HealthController.html).\ -> To customize the health check and add additional checks, you can override the `Rails::HealthController` class.\ +> [!NOTE] +> The default health check path for Rails is `/up`. [Learn more in the Rails guides](https://edgeapi.rubyonrails.org/classes/Rails/HealthController.html). +> To customize the health check and add additional checks, you can override the `Rails::HealthController` class. > You can find an example that also checks the database connection [in this file](../templates/app/controllers/rails/health_controller.rb). ## Verify diff --git a/ruby_on_rails/suggested_libraries.md b/ruby_on_rails/suggested_libraries.md index 6cad8d0e..8e0aeb49 100644 --- a/ruby_on_rails/suggested_libraries.md +++ b/ruby_on_rails/suggested_libraries.md @@ -3,9 +3,11 @@ Here is an hopefully up-to-date version of gems which we strongly suggest to include in your project. Please include them or find a good reason not to. -> :exclamation: Please follow the guide of each of these libraries to know how to properly install them. +> [!IMPORTANT] +> Please follow the guide of each of these libraries to know how to properly install them. -> :bulb: **Tip:** Do you know all of them? Do you know why we'd like them to be included? +> [!TIP] +> Do you know all of them? Do you know why we'd like them to be included? ```rb gem 'simple_form' @@ -25,4 +27,5 @@ group :production do end ``` -> :bulb: **Tip:** To install `simple_form`, run `rails generate simple_form:install --bootstrap` (omit the option if not using Bootstrap) after adding it to your Gemfile. +> [!TIP] +> To install `simple_form`, run `rails generate simple_form:install --bootstrap` (omit the option if not using Bootstrap) after adding it to your Gemfile. diff --git a/ruby_on_rails/wicked_pdf.md b/ruby_on_rails/wicked_pdf.md index f017b99f..2ecba75e 100644 --- a/ruby_on_rails/wicked_pdf.md +++ b/ruby_on_rails/wicked_pdf.md @@ -2,7 +2,8 @@ Can be used to generate PDFs and supports HTML to PDF. -> :warning: Up to now, Wicked PDF does not support Bootstrap 4, so if you want to use Bootstrap 4 Templates, use another library. +> [!WARNING] +> Up to now, Wicked PDF does not support Bootstrap 4, so if you want to use Bootstrap 4 Templates, use another library. * Add `gem 'wicked_pdf'` to the main section of `Gemfile` * Add `gem 'wkhtmltopdf-binary'` to `group :development, :test` @@ -20,7 +21,8 @@ By default, it adds no layout, you you may want to add a layout: render pdf: <>, print_media_type: true, layout: 'pdf', disposition: 'attachment' ``` -> :warning: Consider using a job-runner to not block the server during creation of PDFs. +> [!WARNING] +> Consider using a job-runner to not block the server during creation of PDFs. ## Heroku @@ -29,4 +31,5 @@ If you need Arial, you can add the following buildpack on Heroku: `https://github.com/propertybase/heroku-buildpack-fonts` -> :warning: Make sure you add this as a first buildpack before `heroku/ruby`! +> [!WARNING] +> Make sure you add this as a first buildpack before `heroku/ruby`! diff --git a/slack_and_notifications.md b/slack_and_notifications.md index a2590526..cf046c2b 100644 --- a/slack_and_notifications.md +++ b/slack_and_notifications.md @@ -18,7 +18,8 @@ One notification you may want to receive on this channel is about when a new dep order to do that you must be an admin of the Renuo Slack Organisation. If you are not an admin, ask wg-operations to do it for you communicating the `[project-name]`. -> :warning: **You must have already setup [Automatic Deployment through SemaphoreCI](ruby_on_rails/configure_ci.md).** +> [!WARNING] +> You must have already setup [Automatic Deployment through SemaphoreCI](ruby_on_rails/configure_ci.md). If you used Renuo CLI to configure SemaphoreCI, the notifications should be already created. For manual setup, follow these steps: diff --git a/sparkpost_and_mailtrap.md b/sparkpost_and_mailtrap.md index 1a55fcbe..3818d597 100644 --- a/sparkpost_and_mailtrap.md +++ b/sparkpost_and_mailtrap.md @@ -1,8 +1,7 @@ # SparkPost & Mailtrap -> :warning: Always use subaccounts in Sparkpost! - -> Otherwise there may be compliance issues which can lead to the closing down of the whole Renuo account. +> [!WARNING] +> Always use subaccounts in Sparkpost! Otherwise there may be compliance issues which can lead to the closing down of the whole Renuo account. ## Introduction @@ -28,7 +27,8 @@ ## Sparkpost -> :warning: Always use subaccounts for the project, so that the whole account doesn't get suspended / blocked in case of compliance issues! +> [!WARNING] +> Always use subaccounts for the project, so that the whole account doesn't get suspended / blocked in case of compliance issues! 1. Go to and log in with the credentials for sparkpost+_enviroment_@renuo.ch found in the credential store