From f7633a49db68b9599c6564040a2350c5d2ece0fa Mon Sep 17 00:00:00 2001
From: Lambert Theisen <lambert.theisen@rwth-aachen.de>
Date: Tue, 21 Nov 2023 17:31:41 +0100
Subject: [PATCH] Finalise

---
 README.md                                     |  4 +-
 docs/src/lecture/1-git.md                     | 46 +++++++++++++++++++
 docs/src/lecture/2-julia_project_structure.md | 17 ++++---
 docs/src/lecture/3-julia_documentation.md     | 21 ++++-----
 docs/src/lecture/4-julia_testing.md           | 28 +++++------
 5 files changed, 77 insertions(+), 39 deletions(-)

diff --git a/README.md b/README.md
index 02ee1ea..6af164d 100644
--- a/README.md
+++ b/README.md
@@ -8,11 +8,11 @@
 
 1. **Clone the Repository:**
    ```
-   git clone https://github.com/username/project-name.git
+   git clone git@gitlab.mathematik.uni-stuttgart.de:theiselt/SustainableSoftwareEngineering.jl.git
    ```
 2. **Navigate to the Project Directory:**
    ```
-   cd project-name
+   cd SustainableSoftwareEngineering.jl
    ```
 
 ## Running the Project
diff --git a/docs/src/lecture/1-git.md b/docs/src/lecture/1-git.md
index dc456dc..5eb8f96 100644
--- a/docs/src/lecture/1-git.md
+++ b/docs/src/lecture/1-git.md
@@ -24,6 +24,52 @@ Git is a distributed version control system designed to handle everything from s
 
 Source: https://merely-useful.tech/py-rse/figures/git-cmdline/git-remote.png
 
+Here's a concise guide to a basic Git workflow, covering cloning a repository, creating a file, adding it to the repository, committing, and pushing the changes:
+
+## Basic Git Workflow
+
+0. Create Repo on the Gitlab instance in the Webbrowser
+
+1. **Clone the Repository**
+   Clone the remote repository to your local machine:
+   ```
+   git clone https://gitlab.mathematik.uni-stuttgart.de/user1234/repository
+   ```
+
+2. **Create a New File**
+   Navigate to the cloned repository directory and create a new file:
+   ```
+   cd repository
+   touch newfile.txt
+   ```
+
+3. **Add the File to Staging**
+   Add the new file to the staging area, preparing it for a commit:
+   ```
+   git add newfile.txt
+   ```
+
+4. **Commit the File**
+   Commit the staged file with a descriptive message:
+   ```
+   git commit -m "Add newfile.txt 😎"
+   ```
+
+5. **Push the Commit to Remote Repository**
+   Push the commit to the remote repository:
+   ```
+   git push origin main
+   ```
+
+## Gitignore
+
+- The `.gitignore`-file to ignore files in the Git (automatically generated files, build folders, ...)
+
+```bash
+# content of .gitignore (dot means hidden file)
+docs/build/*  # (star/asterix is placeholder/wildcard to ignore everything in that folder)
+```
+
 ## Getting Started
 
 To start using Git, first [install it](https://git-scm.com/downloads) on your machine. Then, set up your user name and email with the following commands:
diff --git a/docs/src/lecture/2-julia_project_structure.md b/docs/src/lecture/2-julia_project_structure.md
index e37c03b..4328b77 100644
--- a/docs/src/lecture/2-julia_project_structure.md
+++ b/docs/src/lecture/2-julia_project_structure.md
@@ -5,7 +5,6 @@ This lecture focuses on the structure and management of Julia-specific projects.
 
 ## Creating a Project Using Package Manager
 
-- Steps to create a new Julia project
 - Using the Julia REPL and the Package Manager (`Pkg`)
 - Example command:
 
@@ -20,20 +19,25 @@ pkg> generate MyProject
 
 - The `src` folder: Where the source code lives
 - Structure and naming conventions for source files
+- Can contain multiple files (modules)
 
 ### `docs` Folder
 
-- Purpose of the `docs` folder: Documentation of the project
-- Tools for generating documentation in Julia, e.g., Documenter.jl
+- Where the Documentation of the project lives
+- Tools for generating documentation in Julia, e.g., `Documenter.jl`
 
 ### `examples` Folder
 
 - The `examples` folder: Contains example scripts and notebooks
 - Demonstrating usage and features of the project
 
+### `test` Folder
+
+- The folder containing unit tests in the file `runtests.jl`, explained later
+
 ## README File
 
-- Importance of a `README.md` file in a project
+- Every Git needs a `README.md` file, first starting point when someone opens the repo
 - Key elements to include: project description, installation instructions, usage examples, contact info, ...
 
 ## Project.toml and Manifest.toml
@@ -45,10 +49,9 @@ using Pkg
 Pkg.activate(".")  # or press "]" to go into pkg mode and then type "actiavate" and hit enter
 # Activating project at `~/Desktop/gits/nmh/SustainableSoftwareEngineering.jl`
 ```
-- `Manifest.toml`: Detailed state of the environment for reproducibility
-- Understanding the role of these files in dependency management and version control
+- `Manifest.toml`: Detailed state of the environment for reproducibility (not necessarily needed in Git)
 
-### TOML
+### What, what is TOML?
 TOML (Tom's Obvious, Minimal Language) is a simple, easy-to-read configuration file format. Designed by Tom Preston-Werner in 2013, it aims to be more human-readable and writable than formats like XML or JSON.
 ```toml
 # This is a TOML document
diff --git a/docs/src/lecture/3-julia_documentation.md b/docs/src/lecture/3-julia_documentation.md
index 6395d47..10e0c0b 100644
--- a/docs/src/lecture/3-julia_documentation.md
+++ b/docs/src/lecture/3-julia_documentation.md
@@ -6,15 +6,14 @@ In this lecture, we'll explore how to effectively document Julia code. We'll cov
 
 ### Basics of Doc Strings
 
-- What are doc strings and why they are important
-- Basic syntax for writing doc strings in Julia
+- Docstrings: Documentation that lives side-by-side with the source code
 
 ### Advanced Features in Doc Strings
 
 - Including mathematical expressions using LaTeX syntax
 - Adding code examples within doc strings
 - Documenting function signatures for clarity
-- Best practices for writing informative and clear doc strings
+- It's best practice to write informative and clear doc strings
 
 ## Code Example: Writing a Doc String
 
@@ -56,6 +55,7 @@ Documenter.jl is a tool for producing documentation in Julia. We'll look at how
 
 - Organizing your documentation structure
 - Writing an index.md file to serve as the entry point
+- See example docu (live)
 
 ## Including Additional Markdown Files
 
@@ -69,19 +69,14 @@ Documenter.jl is a tool for producing documentation in Julia. We'll look at how
 
 ## Inspecting the resulting index.html
 
-- Generating the HTML documentation locally
-- Tips for inspecting and testing the `index.html` file
+- Generating the HTML documentation locally, and open in local webbrowser
 
-## Building a Documentation Website
+## Optional: Building a Documentation Website
 
-### Hosting Documentation Files
+### Optional: Continuous Integration for Documentation Updates
 
-- Options for hosting the build files to create a publicly accessible documentation website
-- Platforms like GitHub Pages and ReadTheDocs
-
-### Continuous Integration for Documentation Updates
-
-- Setting up CI workflows to automatically update documentation
+- Setting up CI workflows to automatically update documentation and host it
+- Rather needed for big open source projects
 
 ---
 
diff --git a/docs/src/lecture/4-julia_testing.md b/docs/src/lecture/4-julia_testing.md
index 2c17b4b..6cedb22 100644
--- a/docs/src/lecture/4-julia_testing.md
+++ b/docs/src/lecture/4-julia_testing.md
@@ -1,21 +1,20 @@
 
 # Julia: Testing
 
-This lecture aims to provide a comprehensive guide on testing practices in Julia. We will explore the importance of unit tests, delve into coverage aspects, and discuss the integration of automatic testing using continuous integration (CI) tools.
+
 
 ## Importance of Testing
 
-- Why testing is crucial in software development.
+- Why testing is crucial in software development: Have working version in Git, document intended behavior of functions
 - Types of tests: Unit tests, integration tests, etc.
 
 ## Unit Tests in Julia
 
-- Overview of unit testing in Julia.
 - Using the `Test` standard library.
 
 ### Writing Unit Tests
 
-- Basic structure of a unit test.
+- Basic structure of a unit test: Valid Julia code with macro annotations (`@`)
 - Assertions: `@test`, `@test_throws`, `@testset`, etc.
 
 ### Example: Unit Test Tutorial
@@ -36,7 +35,7 @@ Create a file named `test_add.jl`:
 
 ```julia
 using Test
-include("add.jl") # Include the file containing the `add` function
+include("add.jl") # Include the file containing the `add` function, or load package
 
 @testset "Addition Tests" begin
     @test add(2, 2) == 4
@@ -65,10 +64,12 @@ Once you have written your tests, it's important to know how to run them to chec
 Alternatively, you can run your tests directly from the command line without entering the REPL:
 
 - Navigate to your project directory.
-- Run `julia --project=@. -e 'using Pkg; Pkg.test()'`.
+- Run `julia --project=@. -e 'using Pkg; Pkg.test()'` (`@.` means to search for a folder with a `Project.toml` btw)
 
 This command will execute all tests defined in your project's `test` directory.
 
+#### An example output
+
 ```julia
 # Addition Tests: Test Failed at XXX/gits/nmh/SustainableSoftwareEngineering.jl/test/test_add.jl:7
 #   Expression: add(0, 0) == 1
@@ -87,21 +88,14 @@ This command will execute all tests defined in your project's `test` directory.
 # Addition Tests |    3     1      4  0.8s
 ```
 
-## Test Coverage
-
-### Understanding Test Coverage
-
-- What is test coverage and why it matters.
-- Tools for measuring test coverage in Julia, e.g., Codecov or Coveralls.
-
-### Optional: Incorporating Coverage into Tests
+## Optional
 
+### Test Coverage
 - Adding coverage metrics to your test suite.
 - Interpreting coverage reports to improve test quality.
 
-## Optional: Automatic Testing with Continuous Integration
-
-- Using CI for automatic testing.
+### Automatic Testing with Continuous Integration
+- Using CI for automatic testing whenever a commit happened in Git
 
 ## Further reading
 
-- 
GitLab