Merge pull request #86 from WildCodeSchool/code-tours

updated code tours
WildCodeSchool · Aug 9, 2023 · d120274 · d120274
2 parents 5ccb9d6 + 4667273
commit d120274
Show file tree

Hide file tree

Showing 5 changed files with 82 additions and 75 deletions.
diff --git a/.tours/global-behaviour.tour → .tours/01-get-started.tour b/.tours/global-behaviour.tour → .tours/01-get-started.tour
@@ -1,6 +1,6 @@
 {
   "$schema": "https://aka.ms/codetour-schema",
-  "title": "01: Global behaviour",
+  "title": "01: Get started",
   "steps": [
     {
       "file": "README.md",
@@ -10,28 +10,23 @@
     {
       "file": "package.json",
       "description": "Here are the scripts we spoke about in the README.\nEven if you don't understand the exact syntax (and seriously, you don't need to!), know these commands because you'll be using them a lot during your project.\n\nNB: most of these are \"meta-commands\" : they just execute the matching command in the frontend and the backend folders.",
-      "line": 6
+      "line": 16
     },
     {
       "file": "frontend/package.json",
-      "description": "Here we are, in the *frontend* package.json. I insist on this, but **It is not the same as the other one!**\nCommands listed here will have absolutely zero impact on the rest of the project: that's why you should **always** be in your project's root directory in your Terminal before you run any commands.",
+      "description": "Here we are, in the *frontend* package.json. I insist on this, but **It is not the same as the other one!**\nInstalling packages from your project's root directory will have zero impact here: that's why you should **always** be in your frontend directory in your terminal before you run `npm install` commands.",
       "line": 1
     },
     {
       "file": "frontend/package.json",
       "description": "Side note: You may notice there are a lot of (front-specific!) developer dependancies here. They are the packages used to enforce React-only rules (JSX, Accessibility, ...), and would have no interest nor use in the backend folder.",
-      "line": 16
-    },
-    {
-      "file": "frontend/.env.sample",
-      "description": "Here we have a `.env` safe copy. Ask your trainer for more details on it as you see fit, but please note that:\n- every information you don't want everyone to get their hands on should end here. API keys, your bank account number, passwords, ...\n- all the variables you'll list here (in the \".sample\" version) should have **FAKE** values: the `.env.sample` file will go on GHub, whereas the `.env` one won't",
-      "line": 1
+      "line": 15
     },
     {
       "file": "frontend/src/App.jsx",
-      "description": "Here, you may see (at last!) your App itself!\n\nCongrats on finishing this first global CodeTour, for further ado on the frontend architecture you may want to check the next one ;-) ",
-      "line": 1
+      "description": "Here, you may see (at last!) your App itself!\n\nCongrats on finishing this first CodeTour, for further ado on the frontend architecture you may want to check the next one ;-) ",
+      "line": 6
     }
   ],
-  "ref": "master"
-}
+  "ref": "main"
+}
diff --git a/.tours/02-frontend.tour b/.tours/02-frontend.tour
@@ -0,0 +1,42 @@
+{
+  "$schema": "https://aka.ms/codetour-schema",
+  "title": "02: Frontend",
+  "steps": [
+    {
+      "file": "frontend/src/App.jsx",
+      "description": "From your App.jsx file you'll be able to build your application. Consider you're already in the `<body>` tag of your HTML page and code on !",
+      "line": 6
+    },
+    {
+      "file": "frontend/src/App.jsx",
+      "description": "On this very first line, you see the import of another component: Counter (you may delete it if you don't need it, it's just a sample!)\n\nOne thing to note here:\n- this import gets the `Counter.jsx` file situated in the `components` folder (no need to add the \".jsx\" extension in your imports)",
+      "line": 1
+    },
+    {
+      "file": "frontend/src/components/Counter.jsx",
+      "description": "You may store any component you create in the `src/components` folder (thanks Captain Obvious!)\n\nIt'll allow you to keep the `src` folder clean. Feel free to make subfolders to keep it as clean as possible!",
+      "line": 3
+    },
+    {
+      "file": "frontend/src/assets/.gitkeep",
+      "description": "The `src/assets` folder is meant to hold all your non-code files : fonts, images, audio & video files, ...\n\nAs seen in the previous step, please create folders here as you see fit",
+      "line": 1
+    },
+    {
+      "file": "frontend/src/pages/.gitkeep",
+      "description": "The `src/pages` folder is meant to hold components directy called by react-router (or whatever router you're using) (and if you don't understand what I'm saying riht now, don't worry: it'll become clearer soon!)\n\nYou want to store here your \"pages\" (even though React apps don't typically work like vanilla HTML websites and don't know of the \"page\" concept)",
+      "line": 1
+    },
+    {
+      "file": "frontend/src/services/.gitkeep",
+      "description": "This one is a bit trickier to explain... Sometimes, in your React app, you'll need some files which are not components at all: a custom hook, redux files, an API abstraction layer, etc... The `src/services` folder is here for that purpose exactly.\n\nDon't worry if you don't have anything to put in there for now: you'll know when you need it ;-)",
+      "line": 1
+    },
+    {
+      "file": "frontend/src/App.jsx",
+      "description": "You finished the frontend CodeTour: you're ready to build your React application!",
+      "line": 6
+    }
+  ],
+  "ref": "main"
+}
diff --git a/.tours/03-backend.tour b/.tours/03-backend.tour
@@ -5,53 +5,58 @@
     {
       "file": "backend/index.js",
       "description": "Aaah, the `backend` folder ! \n\n_Before we begin, a fair warning: it's a bit more advanced than what you've seen previously, so don't dive in there too soon or you may get overwhelmed!_\n\nStill there ? Okay, here we go !",
-      "line": 15
+      "line": 1
     },
     {
       "file": "backend/index.js",
-      "description": "The irst file you'll run through is the global `index.js`\nIt's just there to set things in motion, and we'll write very few lines of code here:\n- We set environment variables (Hello `.dotenv` !)\n- We call the `src/app.js` file (that's our real app, more on that in a few seconds)\n- We make our app start listening on a specific port (otherwise, even with the best code in the world it would d absolutely nothing)",
-      "line": 1
+      "description": "The first file you'll run through is the global `index.js`\nIt's just there to set things in motion, and we'll write very few lines of code here:\n- We set environment variables (Hello `.dotenv` !)\n- We call the `src/app.js` file (that's our Express app, more on that in a few seconds)\n- We make our app start listening on a specific port (otherwise, even with the best code in the world it would do absolutely nothing)",
+      "line": 12
     },
     {
       "file": "backend/src/app.js",
-      "description": "In the `src/app.js` file, we set up Express and app-wise middlewares (bits of code which are independent from our routes). For example, in this case we:\n- use the `cors` package to specify who has the right to call our backend\n- use the `express.json()` middleware to be able to read our client's request's **body**\n- use the `express.static()` middleware to allow files situated in the `public` folder to be accessed directly, without using routes\n\nWe also call for `src/router.js`, our next stop...",
-      "line": 1
+      "description": "In the `src/app.js` file, we set up Express and app-wise middlewares (bits of code which are independent from our routes). Each part has its own purpose, and sooner or later you will have to read each of them :p",
+      "line": 5
     },
     {
-      "file": "backend/src/router.js",
-      "description": "Here, we'll specify which routes are available, and what does every one of them do.\n\nFor lisibility's sake, we don't write route-specifid code, but instead link to methods situated in *Controllers*\n\nFor example, if your client calls a \"GET /items/17\", the request will be redirected to the \"read\" method of the ItemController class.",
-      "line": 1
+      "file": "backend/src/app.js",
+      "description": "We also call for `src/router.js`, our next stop...",
+      "line": 91
     },
     {
-      "file": "backend/src/controllers/ItemController.js",
-      "description": "Ah, here we are!\n\nThis \"read\" method in ItemController is a classic Express route middleware: given a request (`req`) and a response (`res`) variables, it'll execute code and try to satisfy your clients demands",
+      "file": "backend/src/router.js",
+      "description": "Here, we'll specify which routes are available, and what each of them does.\n\nFor the sake of readability, we don't detail route logic here, but instead link to methods situated in *controllers*.\n\nFor example, if your client calls a \"GET /items/17\", the request will be redirected to the \"read\" method in the `src/controllers/itemControllers.js` file.",
       "line": 16
     },
     {
-      "file": "backend/src/controllers/ItemController.js",
-      "description": "Every route middleware's goal is to `res.send` something, be it useful data or an error code. Here you may see we have several possibilities:\n- If we found the item our client requested (remember the \"GET /items/17\" call ?), we send it\n- If we did not find it, we send a 404 (\"Content not found\") status\n- If something goes wrong (MySQL global error, syntax typo ,...) we send a 500 (\"Internal server error\") code (we don't want potential attackers to know what broke !)",
-      "line": 23
+      "file": "backend/src/controllers/itemControllers.js",
+      "description": "Ah, here we are!\n\nThis \"read\" method in `src/controlles/itemControllers.js` is a classic Express route handler: given a request (`req`) and a response (`res`) variables, it'll execute code and try to satisfy your clients demands",
+      "line": 19
     },
     {
-      "file": "backend/src/controllers/ItemController.js",
-      "description": "Now, I'm speaking about MySQL errors but there are no \"SELECT * FROM item\" queries here, there's just this `models.item.find()` call...\n\nThat's normal, because your requests manipulate an _Entity_, a _Model_ of your target (here, an item). So we'll have to go to the `src/models/ItemManager.js` file!",
-      "line": 17
+      "file": "backend/src/controllers/itemControllers.js",
+      "description": "Every route handler's goal is to `res.send` something, be it useful data or a status code. Here you may see we have several possibilities:\n- If we found the item our client requested (remember the \"GET /items/17\" call ?), we send it\n- If we did not find it, we send a 404 (\"Content not found\") status\n- If something goes wrong (MySQL global error, syntax typo ,...) we pass the error to `next` so Express handles it: by default, it will send a 500 (\"Internal server error\") code (we don't want potential attackers to know what broke !)",
+      "line": 26
     },
     {
-      "file": "backend/src/models/ItemManager.js",
-      "description": "Ah, here we are, we found our SQL queries!\n\nAs you can see, every method here is dead simple: \"do something with the DB, and return the result\".\nThat allows us to regroup **all** our queries in the same files, t make it easier to maintain.\n\nHmm, but although we're in the Item model, I can't see the `find` method...\nOur ItemManager is a specialized AbstractManager (that's OOP for you!), we may as well go and see what this one does ?",
-      "line": 3
+      "file": "backend/src/controllers/itemControllers.js",
+      "description": "Now, I'm speaking about MySQL errors but there are no `SELECT * FROM item` queries here, there's just this `tables.item.read()` call...\n\n We're looking into the `tables` object, for a value called `item` on which we call a `read` method...\n\n Maybe this will make more sense after looking at the `src/tables.js` file!",
+      "line": 22
+    },
+    {
+      "file": "backend/src/tables.js",
+      "description": "Ok! Here we are preparing so-called \"managers\" to fill the `tables` object. \n\nThat's normal, because your requests are done using a _Model_ of your target (in our journey, an item). So we'll have to go to the `src/models/ItemManager.js` file!",
+      "line": 8
     },
     {
-      "file": "backend/src/models/AbstractManager.js",
-      "description": "Hah! Nailed it! (At last)\n\nWe have a `find` method, which does our `SELECT * FROM` query.\nAnd looking more in detail, we can imagine why: except for the table name, the query is strictly identical to find a specific item, or book, or car, or unicorn... So, it makes sense to write it onl once and make sure *every* somethingManager has access to it by default, doesn't it ?\n\nNote that the same goes for `findAll` ans `delete`: you'll never have to write these queries in your own managers !",
-      "line": 7
+      "file": "backend/src/models/ItemManager.js",
+      "description": "Ah, here we are, we found our SQL queries!\n\nAs you can see, every method here is dead simple: \"do something with the DB, and return the result\".\nThat allows us to regroup **all** our queries in specialized files. This is easier to maintain.",
+      "line": 28
     },
     {
       "file": "backend/index.js",
       "description": "Congrats on following me through this complex architecture! I hope that's a bit clearer now that it was a while ago!",
-      "line": 3
+      "line": 1
     }
   ],
-  "ref": "master"
-}
+  "ref": "main"
+}
diff --git a/.tours/frontend.tour b/.tours/frontend.tour
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Fixed [issue #84](https://github.com/WildCodeSchool/js-template-fullstack/issues/84): provided lock files for `pnpm` and `yarn`, and fixed pre-commit hook to allow changes in root `package.json`. Thanks to [Ayoub Idrissi Ouedrhiri](https://github.com/ioayoub).
 
+- Updated code tours in `.tours` folder.
+
 ## [4.0.0] - 2023-07-28
 
 ### Added