Phrasing, formatting, and link cleanups across docs

README.md

@@ -1,50 +1,44 @@
 # 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
+> [!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.
 
-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

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)

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/<num>`
 
-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]`.

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.

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 `<head>` tag of the page (not in the `<body>`).
 
-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
 

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
 
@@ -32,13 +33,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