refactor: reorder intro files

02_GET-STARTED.md

@@ -19,8 +19,52 @@ Master fundamental Git concepts and collaborative workflows:
 - **Module 07: Stash** - Temporarily save work without committing
 - **Module 08: Multiplayer Git** - **The Great Print Project** - Real cloud-based collaboration with teammates
 
+## Requirements
+
+### Prerequisites
+
+Install these tools before starting:
+
+**PowerShell 7+**
+
+Download here <https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell-on-windows?view=powershell-7.5#msi>.
+
+```pwsh
+winget install Microsoft.PowerShell 
+```
+
+
+**Git 2.23+**
+
+Download here <https://git-scm.com/install/windows> or install using the command down below
+
+```pwsh
+winget install Git.Git
+```
+
+**Visual Studio Code**
+
+Download here <https://code.visualstudio.com/download> or install using the command down below
+
+```pwsh
+winget install Microsoft.VisualStudioCode
+```
+
+You can also run the one-shot install script if the project is cloned locally. It will check if you have the prerequisites install and clone down the project if not already cloned. Then it will configure git to have sane default.
+```pwsh
+./install.ps1
+```
+or if you don't have the project locally run.
+
+
+REMEMBER read through the script before running it. As a general practice, you shouldn't get comfortable doing this kind of execution, and so it's important to review executing remote scripts.
+```pwsh
+Invoke-RestMethod -Uri https://git.frod.dk/floppydiscen/git-workshop/raw/branch/main/install.ps1 | Invoke-Expression
+```
+
 ## How to Use This Workshop
 
+
 ### For Local Modules (01-07)
 
 1. Navigate to a module directory (e.g., `01-essentials/01-basics`)
@@ -28,6 +72,7 @@ Master fundamental Git concepts and collaborative workflows:
 3. Run `./setup.ps1` to create the challenge environment
 4. Complete the challenge using git commands
 5. Run `./verify.ps1` to check if you've solved it correctly
+6. If you mess up the challenge just run `.\reset.ps1`
 6. Move to the next module
 
 **Quick Reference**: See [GIT-CHEATSHEET.md](GIT-CHEATSHEET.md) for a comprehensive list of all Git commands covered in this workshop. Don't worry about memorizing everything - use this as a reference when you need to look up command syntax!
@@ -56,6 +101,12 @@ If you encounter an "execution policy" error when running scripts, open PowerShe
 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 ```
 
+And to revert back to the default policy
+
+```pwsh
+Set-ExecutionPolicy -ExecutionPolicy Restricted -Scope CurrentUser
+```
+
 Then run scripts using:
 ```pwsh
 .\setup.ps1
@@ -63,49 +114,6 @@ Then run scripts using:
 .\reset.ps1
 ```
 
-## Requirements
-
-### Prerequisites
-
-Install these tools before starting:
-
-**PowerShell 7+**
-```pwsh
-winget install Microsoft.PowerShell
-```
-
-**Git 2.23+**
-```pwsh
-winget install Git.Git
-```
-
-**Visual Studio Code**
-```pwsh
-winget install Microsoft.VisualStudioCode
-```
-
-You can also run the one-shot install script if the project is cloned locally.
-It will check if you have the prerequisites install and clone down the project
-if not already cloned. Then it will configure git to have sane default.
-```pwsh
-./install.ps1
-```
-or if you don't have the project locally run.
-
-
-REMEMBER read through the script before running it. As a general practice, you
-shouldn't get comfortable doing this kind of execution, and so it's important
-to review executing remote scripts.
-```pwsh
-Invoke-RestMethod -Uri https://git.frod.dk/floppydiscen/git-workshop/raw/branch/main/install.ps1 | Invoke-Expression
-```
-
-### Quick Start
-
-1. **Install the prerequisites above**
-2. **Clone this repository**
-3. **Configure Git** (see below for recommended settings)
-
 ## Git Configuration
 
 Before starting the workshop, configure Git with your identity and recommended settings:
@@ -269,31 +277,3 @@ By completing this workshop, you'll be able to:
 - **Use SSH keys for secure Git authentication**
 
 These are professional-level Git skills used daily by developers at tech companies.
-
----
-
-## Repository Structure
-
-```
-git-workshop/
-├── README.md                          # This file
-├── INSTALLATION.md                    # Installation guide
-├── install.ps1                        # Automated installation script
-├── GIT-CHEATSHEET.md                  # Quick reference for all Git commands
-├── BEST-PRACTICES.md                  # Git best practices
-├── COMMIT-MESSAGES.md                 # Guide to writing good commit messages
-├── WHAT-IS-GIT.md                     # Introduction to Git concepts
-│
-└── 01-essentials/                     # Core Git skills (8 modules)
-    ├── 01-basics/                     # Initialize, commit, status
-    ├── 02-history/                    # Log, diff, show
-    ├── 03-branching-and-merging/      # Branches and merging
-    ├── 04-merge-conflict/             # Resolve merge conflicts
-    ├── 05-cherry-pick/                # Apply specific commits
-    ├── 06-revert/                     # Safe undoing
-    ├── 07-stash/                      # Save work-in-progress
-    └── 08-multiplayer/                # Real collaboration (cloud-based)
-        ├── README.md                  # Student guide
-        ├── 01_FACILITATOR.md          # Facilitator setup guide
-        └── 02_AZURE-DEVOPS-SSH-SETUP.md  # SSH authentication guide
-```

03_BEST-PRACTICES.md

@@ -110,7 +110,7 @@ Nothing creates unnecessary conflicts like two people reformatting the same file
 
 **Do this:**
 - Agree on code formatting standards as a team
-- Use automatic formatters (Prettier, Black, etc.)
+- Use automatic formatters (Prettier, Black, clang-format, etc.)
 - Configure your editor to format on save
 - Run formatters before committing
 
@@ -122,16 +122,22 @@ Renaming a widely-used function or moving files around will conflict with almost
 
 **Do this:**
 - Announce refactors to the team before starting
+    - This is important to coordinate merges of features that are being worked before the great refactoring.
+      A large renaming of namespaces or moving of files becomes hard to deal with when you rely on the old file-structure before the great merge.
+      Instead you should *freeze* any further features until the great refactoring has been completed and then resume feature-building
 - Do them quickly and push immediately
 - Consider doing them when others aren't actively working
 - Keep refactoring commits separate from feature work
+  This keeps your commits clean and doesn't *dirty* the actual work with actual feature work (which also makes it easy to cherry-pick while minimizing conflicts).
 
 ## The Golden Rules
 
 1. **Sync frequently** - Pull before you start, pull before you push
 2. **Commit small** - Many small commits beat one large commit
+   A way to think of it is to keep commit *atomic*. In other words try to make them self-contained units that are easy to `cherry-pick` at a later time.
 3. **Talk to your team** - A quick message prevents hours of conflict resolution
-4. **Stay focused** - One branch = one purpose
+   Communication is key. Even though alot is delegated to the process itself, it's still a good idea to keep communicating with the team regarding larger changes or features being built.
+4. **Stay focused** - One branch = one purpose (and ususally one person)
 5. **Push promptly** - Don't sit on finished work
 
 ## When Conflicts Do Happen
@@ -140,7 +146,7 @@ Even with best practices, conflicts will occur. When they do:
 
 1. **Don't panic** - Conflicts are normal, not failures
 2. **Read carefully** - Understand both sides before choosing
-3. **Test after resolving** - Make sure the merged code actually works
+3. **Test after resolving** - Make sure the merged code actually works. A usual, and rather basic test flow is build -> test -> run
 4. **Ask if unsure** - If you don't understand the other person's code, ask them
 
 Remember: merge conflicts are a communication problem as much as a technical one. The best tool for reducing conflicts is talking to your team.