Linearize ASG among other improvements by cb341 · Pull Request #442 · renuo/application-setup-guide

cb341 · 2026-04-22T14:58:29Z

Linearize the guide so setup reads top-to-bottom without backtracking.
As this PR strongly leans onto mdbook, I recommend reviewing it beyond the markdown.

Notes

Reorganized SUMMARY.md + Rails README into 5 sequential steps: Create → Deploy → Quality → Monitoring → Customer Plan.
Dropped the first_git_push.md backtrack and the redundant "Initial commit" (rails new already commits).
Wrapped bare URLs in <…> so mdbook renders them as links.
Replaced :tada: / :warning: shortcodes with Unicode emoji (mdbook doesn't expand GFM shortcodes).
Unified note/warning blockquote style and the ⭐️ "template-provided" marker.
Added bin/mdbook-rewrite-links preprocessor to send templates/* non-.md links to GitHub blob URLs.
Dropped the emojitsu CI step, pinned mdbook to 0.4.40.

cb341 · 2026-04-22T15:20:24Z

Files would auto download instead of opening on GitHub.
This is a patch.

cb341 · 2026-04-22T15:20:54Z

 [SemaphoreCI](<https://semaphoreci.com/>).

-ℹ️ _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)._


Notes should be defined in a consistent manner:

yes, github has a default syntax for that

cb341 · 2026-04-22T15:21:13Z

-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`


Fence allows copy-pasting via button

cb341 · 2026-04-22T15:21:30Z

@@ -1,6 +1,6 @@
 # Devise

-:warning: If you are going to use devise we suggest you to [send_emails](send_emails.md) first. :warning:


Wasn't rendering properly on mdbook

I see, use the github ones: https://github.com/orgs/community/discussions/16925

cb341 · 2026-04-22T15:22:29Z

         let(:wallee_transaction_id) { "194681414" }

-         it "goes the 😊 path" do
+         it "goes the happy path" do


I remember that this was causing issues with the derived VCR cassette name.

cb341 · 2026-04-22T15:23:16Z

+- [Getting Started](ruby_on_rails/README.md)

- [Setup]()
+- [Step 1: Create the App]()


I think using "Step 1", "Step 2" makes the setup guide a lot easier to follow

lukasbischof

Thanks for your efforts to optimise this guides, I think it's nice to streamline the process a bit and I like the new structure 👍

lukasbischof · 2026-04-23T10:11:48Z

 * 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).


Not sure if this link makes sense, it's invalid and that's a guide so you're reading it

that's fair

lukasbischof · 2026-04-23T11:38:24Z

+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:


What the heck is hub?

Why don't we incentivise to use gh repo create?

gh repo create renuo/[my-project] --private --source=.

Yes I agree, let's update it

yes, please. switch to gh

lukasbischof · 2026-04-23T11:50:20Z

-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


That's still valid, isn't it?

lukasbischof · 2026-04-23T11:52:00Z

+* SEO
+  * redirect non-www to www
+  * Header tags
+* [Wicked PDF](wicked_pdf.md) `gem wicked_pdf`


Generally not sure if we should still recommend wicked_pdf… It's based on wkhtmltopdf which was archived in 2023 and generally does not support a lot of css features

lukasbischof · 2026-04-23T12:00:46Z

+if ARGV == ["supports", "html"]
+  exit 0
+end
+
+_context, book = JSON.parse($stdin.read)
+book["sections"].each { |section| walk(section) }
+puts JSON.generate(book)


I have no clue what you're doing here 😅

lukasbischof · 2026-04-23T12:03:25Z

-* 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.


No more checklist?

lukasbischof · 2026-04-23T12:03:42Z

-
-We want you to know exactly the reason behind each single step of this guide.
-
-Thank you for your work and have fun! :tada:


No more fun allowed either xD

lukasbischof · 2026-04-23T12:06:25Z

+- [Getting Started](ruby_on_rails/README.md)

- [Setup]()
+- [Step 1: Create the App]()


Why are these links leading to nowhere?

They are headings

lukasbischof · 2026-04-23T12:13:42Z

+    - [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)


Wouldn't the steps be initialise git repo, configure gitflow (do we even need the git extension?), create and configure github repo

i agree

git push

git repository

coorasse

Nice work.
There some parts that I'd like to keep for historical reasons and some rephrasings I do not approve, but overall the changes are good. Can you please extract the emoji changes in a separate PR? They have nothing to do with the rest and we can get them merged separately. Some separate things (an agent will do this for you in a minute):

mdbook changes and fixes (also make sure the readme command works)
emojis
warnings,notes,and other sections normalized with github formatting
content

I'd like this PR to contain only the changes to the actual content, so I can review the last two files. Thanks!

coorasse · 2026-04-23T14:05:08Z

 * 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).


coorasse · 2026-04-23T15:53:43Z

-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.


this was a very important note to explain how this guide was born and evolved. I'd not drop it.

coorasse · 2026-04-23T15:54:20Z

-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**.


this is also important introduction about what will happen and the main purpose

coorasse · 2026-04-23T15:56:57Z

+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.


I think you should read the naming convention when you need to give a name to the project. It's of no use at this step, without a purpose. This is covered by the first step in the rails part of the guide.

Knowing giflow is, instead, important, but I don't think it should actually be part of this guide, but of the wiki.

Security is also important but it tells me things I cannot yet do since I don't have a repo, so it should rather be at the very end.

coorasse · 2026-04-23T15:57:56Z

-**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.).


this will slow down the application setup. It's more important to go ahead and setup everything that is mandatory. When the project is ready, everyone can start working and you can go through the optional parts

coorasse · 2026-04-23T16:09:30Z

-**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


Suggested change

> **Note:** If you are using Heroku, the latest Ruby / node version may not yet

> **Note:** If you are using Heroku or Deploio, the latest Ruby / node version may not yet

coorasse · 2026-04-23T16:09:51Z

@@ -1,6 +1,6 @@
 # Devise

-:warning: If you are going to use devise we suggest you to [send_emails](send_emails.md) first. :warning:


I see, use the github ones: https://github.com/orgs/community/discussions/16925

coorasse · 2026-04-23T16:10:35Z

+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:


yes, please. switch to gh

coorasse · 2026-04-23T16:11:19Z

-git add .
-git commit -m "Initial commit"
 git push -u origin main


I am surprised that this is not needed. I haven't double-checked myself, but is strange.

coorasse · 2026-04-23T16:12:00Z

next time, do the emoji changes in a separate PR, so we can get those merged. They have nothing to do with the content change and they are distracting a lot.

cb341 added 5 commits April 22, 2026 16:08

Update ASG

fbb6576

Fix mdbook command

a654854

Update the display of stars

218591e

e.g.

f15b6ff

Update Gitlab hint

276d07f

cb341 self-assigned this Apr 22, 2026

cb341 added 3 commits April 22, 2026 17:11

Rephrasings and stuff

822dae0

Configure link rewriting

c994649

Improve formatting

26e8ae3

cb341 commented Apr 22, 2026

View reviewed changes

cb341 and others added 9 commits April 22, 2026 17:41

Comments from template repo

fac535a

Update NOTES

9201ab7

Quickfixes

0364364

Merge branch 'main' into feature/improve-docs

9bb6941

Fix indent

9b71fb5

Improvements

d1c1518

Fix summary

ebcf7e6

Get rid of emojify

3f50e88

Attmept fix

fe0b37f

cb341 changed the title ~~Linearize ASG~~ Linearize ASG + other improvements Apr 22, 2026

cb341 marked this pull request as ready for review April 22, 2026 21:47

cb341 changed the title ~~Linearize ASG + other improvements~~ Linearize ASG among other improvements Apr 22, 2026

cb341 requested a review from lukasbischof April 23, 2026 08:55

lukasbischof reviewed Apr 23, 2026

View reviewed changes

cb341 requested a review from coorasse April 23, 2026 14:01

coorasse requested changes Apr 23, 2026

View reviewed changes

		@@ -1,6 +1,6 @@
		# Devise

		:warning: If you are going to use devise we suggest you to [send_emails](send_emails.md) first. :warning:

		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


		We want you to know exactly the reason behind each single step of this guide.

		Thank you for your work and have fun! :tada:

	> Note: If you are using Heroku, the latest Ruby / node version may not yet
	> Note: If you are using Heroku or Deploio, the latest Ruby / node version may not yet

Conversation

cb341 commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cb341 Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lukasbischof left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coorasse left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

cb341 commented Apr 22, 2026 •

edited

Loading

cb341 Apr 22, 2026 •

edited

Loading