81 | Ask for help from the teacher 82 | 83 | ### Merging changes into your local branch 84 | 85 | Merging combines your local changes with changes made by others. 86 | 87 | Typically, you'd merge a remote-tracking branch (i.e., a branch fetched from a remote repository) with your local branch: 88 | 89 | $ git merge origin/main 90 | # will merge the remote origin into local main 91 | 92 | :neutral_face: Stuck?
93 | Ask for help from the teacher 94 | 95 | ### Pulling changes from a remote repository 96 | 97 | `git pull`` is a convenient shortcut for completing both `git fetch` and `git merge` in the same command: 98 | 99 | $ git pull origin main 100 | # Grabs online updates and merges them with your local work 101 | 102 | Because pull performs a merge on the retrieved changes, you should ensure that your local work is committed before running the pull command. If you run into a merge conflict you cannot resolve, or if you decide to quit the merge, you can use `git merge --abort` to take the branch back to where it was in before you pulled. 103 | 104 | :anguished: Stuck?
105 | Ask for help from the teacher 106 | 107 | ## :tada: Great job! 108 | 109 | You have learnt: 110 | 111 | 1. Forking a repo at GitHub 112 | 2. Git push 113 | 3. Git fetch 114 | 4. Git pull -------------------------------------------------------------------------------- /Workshop - GIT/06_collaboration.md: -------------------------------------------------------------------------------- 1 | ## Collaboration with GitHub 2 | 3 | Explore collaborative workflows using GitHub: 4 | 5 | ## Fork a repo 6 | 7 | Go to [this tutorial](https://help.github.com/articles/fork-a-repo) 8 | Then come back here, we’ll wait. 9 | 10 | 11 | ## Pull requests 12 | 13 | Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch. 14 | 15 | More in depth information can be found on the [GitHub page about Pull Requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) 16 | 17 | ### Creating pull requests. 18 | 19 | GitHub has an excellent page on how to create a pull request. 20 | You can find that page here [https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) 21 | 22 | ### Reviewing and merging pull requests. 23 | 24 | In a pull request, you can review and discuss commits, changed files, and the differences (or "diff") between the files in the base and compare branches. 25 | 26 | Find more in depth info on the [GitHub page about Reviewing Pull Requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) 27 | 28 | :bulb: Sometimes you created a pull request and you want to request a review, [this page](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) gives you more in depth information on how to ask someone to review your pull request. 29 | 30 | ## Issues 31 | 32 | GitHub Issues are items you can create in a repository to plan, discuss and track work. 33 | 34 | Issues are simple to create and flexible to suit a variety of scenarios. You can use issues to track work, give or receive feedback, collaborate on ideas or tasks, and efficiently communicate with others. 35 | 36 | ### Creating an issue 37 | 38 | Issues let you track your work on GitHub. When you mention an issue in another issue or pull request, the issue's timeline reflects the cross-reference so that you can keep track of related work. To indicate that work is in progress, you can link an issue to a pull request. When the pull request merges, the linked issue automatically closes. 39 | 40 | To create an issue, there are multiple options available in GitHub. Follow the detailed information on the [GitHub page about creating an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue) 41 | 42 | ### Linking a pull request to an issue 43 | 44 | You can link a pull request or branch to an issue to show that a fix is in progress and to automatically close the issue when the pull request or branch is merged. 45 | 46 | You can link an issue to a pull request manually or using a supported keyword in the pull request description. 47 | 48 | When you link a pull request to the issue the pull request addresses, collaborators can see that someone is working on the issue. 49 | 50 | More information about this option can be found on the [GitHub page about linking an Issue to a Pull Request](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) 51 | 52 | 53 | ### Assigning issues and pull requests 54 | 55 | Sometimes it's handy to know who is working on an issue, or better assign someone to an issue or pull requests because they have the required knowledge. 56 | 57 | If that is the case, you can assign someone to an issue or pull requests, more information can be found on the [GitHub page about assigning Issues and Pull Requests](https://docs.github.com/en/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users) -------------------------------------------------------------------------------- /Workshop - GIT/07_tips.md: -------------------------------------------------------------------------------- 1 | ## :rocket: Best Practices and Tips 2 | 3 | Using Git best practices, teams can coordinate all changes in a software project and utilize fast branching to help teams quickly collaborate and share feedback, leading to immediate, actionable changes. 4 | 5 | ### Make incremental, small changes 6 | 7 | Write the smallest amount of code possible to solve a problem. After identifying a problem or enhancement, the best way to try something new and untested is to divide the update into small batches of value that can easily and rapidly be tested with the end user to prove the validity of the proposed solution and to roll back in case it doesn't work without deprecating the whole new functionality. 8 | 9 | Committing code in small batches decreases the likelihood of integration conflicts, because the longer a branch lives separated from the main branch or codeline, the longer other developers are merging changes to the main branch, so integration conflicts will likely arise when merging. Frequent, small commits solves this problem. Incremental changes also help team members easily revert if merge conflicts happen, especially when those changes have been properly documented in the form of descriptive commit messages. 10 | 11 | ### Keep commits atomic 12 | 13 | Related to making small changes, atomic commits are a single unit of work, involving only one task or one fix (e.g. upgrade, bug fix, refactor). Atomic commits make code reviews faster and reverts easier, since they can be applied or reverted without any unintended side effects. 14 | 15 | The goal of atomic commits isn't to create hundreds of commits but to group commits by context. For example, if a developer needs to refactor code and add a new feature, she would create two separate commits rather than create a monolithic commit which includes changes with different purposes. 16 | 17 | ### Develop using branches 18 | 19 | Using branches, software development teams can make changes without affecting the main codeline. The running history of changes are tracked in a branch, and when the code is ready, it's merged into the main branch. 20 | 21 | Branching organizes development and separates work in progress from stable, tested code in the main branch. Developing in branches ensures that bugs and vulnerabilities don't work their way into the source code and impact users, since testing and finding those in a branch is easier. 22 | 23 | ### Write descriptive commit messages 24 | 25 | Descriptive commit messages are as important as a change itself. Write descriptive commit messages starting with a verb in present tense in imperative mood to indicate the purpose of each commit in a clear and concise manner. Each commit should only have a single purpose explained in detail in the commit message. The Git documentation provides guidance on how to write descriptive commit messages: 26 | 27 | Describe your changes in imperative mood, e.g. “make xyzzy do frotz” instead of “[This patch] makes xyzzy do frotz” or “[I] changed xyzzy to do frotz,” as if you are giving orders to the codebase to change its behavior. Try to make sure your explanation can be understood without external resources. Instead of giving a URL to a mailing list archive, summarize the relevant points of the discussion. 28 | 29 | Writing commit messages in this way forces software teams to understand the value an add or fix makes to the existing code line. If teams find it impossible to find the value and describe it, then it might be worth reassessing the motivations behind the commit. There's always time to commit later, as long changes are stashed and there's consistency in commits. 30 | 31 | ### Obtain feedback through code reviews 32 | 33 | Requesting feedback from others is an excellent way to ensure code quality. Code reviews are an effective method to identify whether a proposal solves a problem in the most effective way possible. Asking individuals from other teams to review code is important, because some areas of the code base might include specific domain knowledge or even security implications beyond the individual contributor's attributions. 34 | 35 | ### Identify a branching strategy 36 | 37 | Determining a single branching strategy is the solution to a chaotic development experience. 38 | 39 | While there are several approaches to development, the most common are: 40 | - Centralized workflow: Teams use only a single repository and commit directly to the main branch. 41 | - Feature branching: Teams use a new branch for each feature and don't commit directly to the main branch. 42 | - GitFlow: An extreme version of feature branching in which development occurs on the develop branch, moves to a release branch, and merges into the main branch. 43 | - Personal branching: Similar to feature branching, but rather than develop on a branch per feature, it's per developer. Every user merges to the main branch when they complete their work. -------------------------------------------------------------------------------- /Workshop - GIT/08_resources.md: -------------------------------------------------------------------------------- 1 | 2 | ### References and Further reading 3 | 4 | We throughly recommend these resources to continue your Git practice: 5 | 6 | - http://try.github.com Another 7 | beginners tutorial for git 8 | - http://git-scm.com Official 9 | website, with very useful help, book and videos 10 | - http://gitref.org 11 | - http://www.kernel.org/pub/software/scm/git/docs/everyday.html 12 | - https://education.github.com/git-cheat-sheet-education.pdf Cheatsheet for Git commands 13 | -------------------------------------------------------------------------------- /Workshop - Operating systems and Bash/01_introduction.md: -------------------------------------------------------------------------------- 1 | # Introduction to the Shell 2 | The shell is a crucial component of an operating system, acting as an intermediary between the user and the system’s core functions. 3 | During this workshop you will learn: 4 | 5 | - What is a shell and what is it used for 6 | - How you can use the shell to navigate, manipulate files and directories and more 7 | - How to write shell scripts 8 | - And some tips for using the shell or shell scripts 9 | 10 |
11 | 12 | ## Significance 13 | 1. **User Interface:** The shell provides a user interface, allowing users to interact with the operating system. This can be through a command-line interface (CLI) or a graphical user interface (GUI). 14 | 2. **Command Execution:** It interprets and executes user commands. When you type a command in the terminal, the shell processes it and communicates with the operating system to perform the requested action. 15 | 3. **Scripting and Automation:** Shells support scripting, enabling users to write scripts to automate repetitive tasks. This is particularly useful for system administrators and developers. 16 | 4. **Customization:** Users can customize their shell environment to suit their preferences, such as setting up aliases, functions, and environment variables. 17 | 5. **Process Management:** The shell allows users to manage processes, including starting, stopping, and monitoring them. This is essential for multitasking and system management. 18 | 19 | ## Actions 20 | 1. **Command Interpretation:** The shell interprets the commands entered by the user and translates them into actions that the operating system can execute. 21 | 2. **File Manipulation:** It provides commands for file manipulation, such as creating, deleting, copying, and moving files and directories. 22 | 3. **Program Execution:** The shell can launch and manage the execution of programs. It can run programs in the foreground or background and handle input/output redirection. 23 | 4. **Environment Control:** The shell manages the user environment, including setting environment variables that can affect the behavior of running programs. 24 | 5. **Security:** Shells can enforce security policies by restricting access to certain commands or files, ensuring that only authorized users can perform specific actions. 25 | 26 |
27 | 28 | ## Shells 29 | There are several popular shells used in operating systems, each with its own features and advantages. 30 | 31 |
32 |
33 | ### Bash (Bourne Again Shell)
34 | This is probably the most widely used shell in Linux and macOS. \
35 | It’s the default shell on many Linux distributions and macOS.
36 |
37 | Top features:
38 | - Supports scripting
39 | - Command history
40 | - Tab completion
41 |
42 | 43 | 44 |
45 |
46 | ### Zsh (Z Shell)
47 | A popular shell among power users and developers. \
48 | Often used with the Oh My Zsh framework for additional plugins and themes.
49 |
50 | Top features:
51 | - Improved tab completion
52 | - Better scripting capabilities
53 | - Customization
54 |
55 | 56 | 57 |
58 |
59 | ### Fish (Friendly Interactive Shell)
60 | This shell is known for its user-friendly features. \
61 | It is gaining traction for its ease of use and modern features.
62 |
63 | Top features:
64 | - Syntax highlighting
65 | - Autosuggestions
66 | - Web-based configuration interface
67 |
68 | 69 | 70 |
71 |
72 | ### Powershell
73 | This shell is primarily used in Windows environments. \
74 | It is the default shell in Windows but is also available for Linux and macOS.
75 |
76 | Top features:
77 | - Object-oriented scripting
78 | - Extensive automation capabilities
79 | - Full integration with .NET
80 |
81 | 82 | 83 |
84 |
85 | ### Dash (Debian Almquist Shell)
86 | A lightweight shell used in Debian-based systems. \
87 | Mostly used in scripts and system initialization.
88 |
89 | Top features:
90 | - Fast execution
91 | - Minimal resource usage
92 | - POSIX compliance
--------------------------------------------------------------------------------
/Workshop - Operating systems and Bash/05_permissions.md:
--------------------------------------------------------------------------------
1 | # Permissions and Ownership
2 | In Unix-like operating systems, managing file permissions and ownership is crucial for maintaining system security and ensuring that users have appropriate access to files and directories. Each file and directory has a set of permissions that determine who can read, write, or execute them. These permissions are divided into three categories: owner, group, and others.
3 |
4 | ## File permissions
5 | In Unix-like systems, each file and directory has a set of permissions that determine who can read, write, or execute them. These permissions are divided into three categories:
6 |
7 | - **Owner**: The user who owns the file.
8 | - **Group**: The group that owns the file.
9 | - **Others**: All other users.
10 |
11 | Each category has three types of permissions:
12 | - **Read (r)**: Permission to read the file or list the directory contents.
13 | - **Write (w)**: Permission to modify the file or directory.
14 | - **Execute (x)**: Permission to execute the file or access the directory.
15 |
16 | You can view the permissions of a file using the **ls -l** command:
17 | ```sh
18 | ls -l myfile.txt
19 | ```
20 |
21 | Output:
22 |
23 | ```
24 | -rw-r--r-- 1 user group 1234 Oct 3 14:18 myfile.txt
25 | ```
26 |
27 | In the above example `-rw-r--r--` indicates the permissions.
28 | * `-`: File type (dash means a regular file).
29 | * `rw-`: Owner permissions (read and write).
30 | * `r--`: Group permissions (read only).
31 | * `r--`: Others permissions (read only).
32 |
33 | ### Assignment
34 | Use `ls -l` to view the permissions of files in your home directory.
35 |
36 | 37 | 38 | ## Changing permissions 39 | You can change the permissions of a file using the `chmod` command. There are two ways to use `chmod`: symbolic and numeric. 40 | 41 | **Symbolic Mode**: 42 | * `u`: User (owner) 43 | * `g`: Group 44 | * `o`: Others 45 | * `a`: All (user, group, and others) 46 | 47 | ```sh 48 | # Add execute permission for the owner 49 | chmod u+x myfile.txt 50 | 51 | # Remove write permission for the group 52 | chmod g-w myfile.txt 53 | 54 | # Set read and write permissions for all 55 | chmod a+rw myfile.txt 56 | ``` 57 | 58 | ### Assignment 59 | Create a command that adds execute permission for the owner and removes write permission for others on a file. 60 | > *Hint: Use `chmod u+x` and `chmod o-w`.* 61 | 62 |
63 | 64 | **Numeric Mode** 65 | Permissions can also be represented by numbers: 66 | * `r` = 4 67 | * `w` = 2 68 | * `x` = 1 69 | 70 | Combine these values to set permissions. For example, 7 (4+2+1) means read, write, and execute. 71 | 72 | ```sh 73 | # Set permissions to rwxr-xr-- 74 | chmod 755 myfile.txt 75 | ``` 76 | So, the permissions in the above example are: 77 | 78 | - **7 (Owner)**: `rwx` (4 + 2 + 1 = 7) 79 | - **5 (Group)**: `r-x` (4 + 1 = 5) 80 | - **5 (Others)**: `r-x` (4 + 1 = 5) 81 | 82 | ### Assignment 83 | Permissions (Numeric Mode): Write a command that sets the permissions of a file to rwxr-xr-- 84 | > *Hint: Use `chmod 755`.* 85 | 86 |
87 | 88 | ## Ownership 89 | Each file and directory has an owner and a group. You can change the ownership using the `chown` command. 90 | 91 | ```sh 92 | # Change the owner to 'newuser' 93 | chown newuser myfile.txt 94 | 95 | # Change the owner and group 96 | chown newuser:newgroup myfile.txt 97 | ``` 98 | 99 | ### Assignment 100 | Create a command that changes the owner of a file to a different user. 101 | > *Hint: Use `chown newuser`.* 102 | 103 |
-------------------------------------------------------------------------------- /Workshop - Operating systems and Bash/07_ssh.md: -------------------------------------------------------------------------------- 1 | # SSH (Secure Shell) [*optional*] 2 | 3 | SSH (Secure Shell) is a protocol used to securely connect to remote servers. It provides a secure channel over an unsecured network by using encryption. This guide will cover the basics of using SSH, setting up SSH keys for passwordless authentication, and configuring SSH access for multiple users. 4 | 5 |
6 |
7 | 8 | 9 | ### Basic SSH Usage 10 | To connect to a remote server using SSH, use the following command: 11 | 12 | ssh username@hostname 13 | 14 | `username`: The username on the remote server. \ 15 | `hostname`: The IP address or domain name of the remote server. 16 | 17 | If we would login with the credentials `user` for domain `example.com`, it would look like this: 18 | 19 | ssh user@example.com 20 | 21 |
22 | 23 | ### Running Commands on a Remote Server 24 | You can also run commands on a remote server without logging in interactively 25 | 26 | ssh username@hostname '[command]' 27 | 28 | Let's say you want to run the command `ls -la` on the server of `example.com`, we can use: 29 | 30 | ssh user@example.com 'ls -la' 31 | 32 | 33 | ### Using a Specific Port 34 | If your SSH server is running on a non-standard port (e.g., port 2222): 35 | 36 | ssh -p 2222 username@hostname 37 | 38 | 39 | ### Tunneling with SSH 40 | To create an encrypted tunnel to forward a port: 41 | 42 | ssh -L local_port:remote_address:remote_port username@hostname 43 | 44 | 45 | For example, to forward port 8080: 46 | 47 | ssh -L 8080:localhost:80 john@192.168.1.10 48 | 49 | 50 | ### Transferring Files with SCP 51 | To copy files from your local machine to the remote server: 52 | 53 | scp localfile username@hostname:/path/to/remote/file 54 | 55 | For example: 56 | 57 | scp myfile.txt john@192.168.1.10:/home/john/myfile.txt 58 | 59 | 60 |
61 | 62 | ## Using SSH Keys for Authentication 63 | ### Generating SSH Keys 64 | To generate a new SSH key pair, use the ssh-keygen command: 65 | 66 | ssh-keygen -t rsa -b 4096 -C "your_email@example.com" 67 | 68 | - `-t rsa`: Specifies the type of key to create (RSA). 69 | - `-b 4096`: Specifies the number of bits in the key (4096 bits). 70 | - `-C "your_email@example.com"`: Adds a label to the key. 71 | 72 | Follow the prompts to save the key pair to the default location (~/.ssh/id_rsa). 73 | 74 |
75 | 76 | ### Copying the Public Key to the Server 77 | To use the SSH key for authentication, you need to copy the public key to the remote server. You can use the ssh-copy-id command: 78 | 79 | ssh-copy-id username@hostname 80 | 81 | Example: 82 | 83 | ssh-copy-id user@example.com 84 | 85 | Alternatively, you can manually copy the public key: 86 | 87 | Display the public key: 88 | 89 | cat ~/.ssh/id_rsa.pub 90 | 91 | Copy the output and add it to the ~/.ssh/authorized_keys file on the remote server. 92 | 93 |
94 | 95 | ### Connecting Using SSH Keys 96 | Once the public key is added to the remote server, you can connect without a password: 97 | 98 | ssh username@hostname 99 |
100 | 101 | 102 | ## Configuring SSH Access for Multiple Users 103 | ### Setting Up SSH Keys for Multiple Users 104 | To allow multiple group members to connect to a VPS using SSH keys, each member needs to generate their own SSH key pair and add their public key to the server. 105 | 106 | Generate SSH Keys: Each user generates their own SSH key pair using ssh-keygen. 107 | Copy Public Keys to the Server: Each user copies their public key to the server using ssh-copy-id or manually. 108 | 109 |
110 | 111 | ### Adding Multiple Keys to authorized_keys 112 | On the remote server, the ~/.ssh/authorized_keys file can contain multiple public keys. Each key should be on a new line. 113 | 114 | Example: 115 | 116 | ssh-rsa AAAAB3... user1@example.com 117 | ssh-rsa AAAAB3... user2@example.com 118 | ssh-rsa AAAAB3... user3@example.com 119 | 120 |
121 | 122 | ### Managing Access 123 | To manage access, you can add or remove keys from the authorized_keys file. Ensure that the file permissions are set correctly: 124 | 125 | chmod 600 ~/.ssh/authorized_keys 126 | chmod 700 ~/.ssh 127 | 128 |
129 | 130 | ### Group Management 131 | If you want to manage access for a group of users, you can create a group on the server and add users to that group. Ensure that the authorized_keys file is accessible to all group members. 132 | 133 | Example: 134 | 135 | Create a group: 136 | 137 | sudo groupadd sshusers 138 | 139 | Add users to the group: 140 | 141 | sudo usermod -aG sshusers user1 142 | sudo usermod -aG sshusers user2 143 | 144 | Set the correct permissions for the .ssh directory and authorized_keys file: 145 | 146 | sudo chown -R user1:sshusers /home/user1/.ssh 147 | sudo chmod 770 /home/user1/.ssh 148 | sudo chmod 660 /home/user1/.ssh/authorized_keys 149 | 150 |
151 | 152 | ### Securing Your SSH Server 153 | To enhance the security of your SSH server, consider the following configurations in your `/etc/ssh/sshd_config` file: 154 | 155 | Disable Root Login: 156 | 157 | PermitRootLogin no 158 | 159 | Limit User Logins: 160 | 161 | AllowUsers john 162 | 163 | Use Stronger Encryption Algorithms: 164 | 165 | Ciphers aes256-gcm@openssh.com,chacha20-poly1305@openssh.com 166 | 167 | Enable Two-Factor Authentication (2FA): 168 | 169 | AuthenticationMethods publickey,password -------------------------------------------------------------------------------- /Workshop - Operating systems and Bash/08_tips.md: -------------------------------------------------------------------------------- 1 | # Best practices and Tips 2 | 3 | You've learned a lot of commands during this workshop, commands designed for the shell and commands to use in Bash scripting. \ 4 | This page gives a brief overview of best practices and tips for using the shell and Bash. 5 | 6 |
7 | 8 | ### Use Tab Completion 9 | Tab completion helps you quickly complete commands, file names, and directory names. \ 10 | Just start typing and press `Tab` to auto-complete or see suggestions. 11 | 12 | ### Command History 13 | Use the up and down arrow keys to scroll through your command history. \ 14 | This saves time by allowing you to reuse previous commands. 15 | 16 | Use `Ctrl + R` to search through your command history. \ 17 | Start typing a part of the command and it will show the most recent match. 18 | 19 | ### Aliases 20 | Create aliases for frequently used commands to save time. 21 | 22 | alias ll='ls -la' 23 | 24 | Add this to your `.bashrc` or `.bash_profile` to make it permanent. 25 | 26 | ### Use Wildcards 27 | Wildcards can help you work with multiple files at once. 28 | - `*` matches any number of characters. 29 | - `?` matches a single character. 30 | - `[abc]` matches any one of the characters inside the brackets. 31 | 32 | ### Use man and --help 33 | Use the man command to read the manual pages for commands. 34 | 35 | man ls 36 | 37 | Most commands also support `--help` to display a summary of options. 38 | 39 | ls --help 40 | 41 | ### Redirecting Output 42 | Redirect standard output and error to different files. 43 | 44 | command > output.txt 2> error.txt 45 | 46 | ### Background Processes 47 | Run commands in the background by appending `&` at the end. 48 | 49 | long_running_command & 50 | 51 |
52 | 53 | ## Bash Scripting 54 | 55 | 56 | ### Start with a Shebang 57 | Always start your script with a shebang to specify the interpreter. 58 | ```sh 59 | #!/bin/bash 60 | ``` 61 | 62 | ### Make Scripts Executable 63 | Make your script executable using chmod. 64 | 65 | chmod +x script.sh 66 | 67 | ### Use Comments 68 | Use comments to explain your code. This makes it easier to understand and maintain. 69 | ```sh 70 | # This is a comment 71 | echo "Hello, World!" 72 | ``` 73 | 74 | ### Use Variables 75 | Use variables to store and reuse values. 76 | ```sh 77 | name="Alice" 78 | echo "Hello, $name" 79 | ``` 80 | 81 | ### Use Functions 82 | Use functions to organize your code and avoid repetition. 83 | ```sh 84 | greet() { 85 | echo "Hello, $1" 86 | } 87 | greet "Alice" 88 | ``` 89 | 90 | ### Error Handling 91 | Check the exit status of commands to handle errors. 92 | ```sh 93 | if [ $? -ne 0 ]; then 94 | echo "An error occurred" 95 | fi 96 | ``` 97 | 98 | ### Use set Options 99 | Use set options to improve script robustness. 100 | ```sh 101 | set -e: Exit immediately if a command exits with a non-zero status. 102 | set -u: Treat unset variables as an error. 103 | set -o pipefail: Return the exit status of the last command in the pipeline that failed. 104 | set -euo pipefail 105 | ``` 106 | 107 | ### Use read for User Input 108 | Use read to get input from the user. 109 | ```sh 110 | read -p "Enter your name: " name 111 | echo "Hello, $name" 112 | ``` 113 | 114 | ### Debugging 115 | Use `bash -x script.sh` to run your script in debug mode and see each command executed. 116 | 117 | ### Use trap for Cleanup 118 | Use `trap` to execute commands when the script exits, which is useful for cleanup tasks. 119 | 120 | trap 'echo "Cleaning up..."; rm -f temp_file' EXIT -------------------------------------------------------------------------------- /Workshop - Operating systems and Bash/09_resources.md: -------------------------------------------------------------------------------- 1 | # Resources for further learning 2 | For more in depth information about shells, bash scripting and ssh, the following resources could help. 3 | 4 | - https://www.explainshell.com/ 5 | 6 | - https://phoenixnap.com/kb/bash-commands 7 | 8 | - https://dev.to/devrx/shell-scripting-101-essential-commands-for-every-developer-j3p 9 | 10 | - https://www.gnu.org/software/bash/manual/bash.html 11 | 12 | - https://github.com/awesome-lists/awesome-bash 13 | 14 | - https://www.howtogeek.com/362409/what-is-zsh-and-why-should-you-use-it-instead-of-bash/ 15 | 16 | - https://www.sitepoint.com/zsh-tips-tricks/ 17 | 18 | - https://fishshell.com/docs/current/cmds/fish 19 | 20 | - https://github.com/jorgebucaran/awsm.fish 21 | 22 | - https://learn.microsoft.com/en-us/powershell/scripting/learn/more-powershell-learning?view=powershell-7.4 23 | 24 | - https://wiki.archlinux.org/title/Dash 25 | 26 | - https://www.digitalocean.com/community/tutorials/ssh-essentials-working-with-ssh-servers-clients-and-keys 27 | 28 | - https://www.cloudflare.com/learning/access-management/what-is-ssh/ 29 | 30 | - https://opensource.com/article/20/9/ssh -------------------------------------------------------------------------------- /Workshop - Operating systems and Bash/assets/images/bash.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Operating systems and Bash/assets/images/bash.png -------------------------------------------------------------------------------- /Workshop - Operating systems and Bash/assets/images/dash.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Operating systems and Bash/assets/images/dash.png -------------------------------------------------------------------------------- /Workshop - Operating systems and Bash/assets/images/fish.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Operating systems and Bash/assets/images/fish.png -------------------------------------------------------------------------------- /Workshop - Operating systems and Bash/assets/images/powershell.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Operating systems and Bash/assets/images/powershell.png -------------------------------------------------------------------------------- /Workshop - Operating systems and Bash/assets/images/ssh-example.webp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Operating systems and Bash/assets/images/ssh-example.webp -------------------------------------------------------------------------------- /Workshop - Operating systems and Bash/assets/images/zshell.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Operating systems and Bash/assets/images/zshell.png -------------------------------------------------------------------------------- /Workshop - Refactoring/01_introduction.md: -------------------------------------------------------------------------------- 1 | # Hands-On Code Refactoring 2 | 3 | ## Code gets "dirty" 4 | It's the programmer's task to ship features. Once finished with the current feature we move on to the next and the next. But as a project progresses entropy kicks in. This means that code becomes harder to read and to maintain. As a result bugs creep in, the performance goes down and our feature velocity grinds to a halt. 5 | 6 | Code gets "dirty" because of 7 | 8 | - Inexperience 9 | - Hard deadlines 10 | - Shortcuts 11 | - Unknowns 12 | 13 | Another word for "dirty code" is "technical debt" and it's our task to fight it proactively during the development process by refactoring our code. 14 | 15 | ## What is code refactoring? 16 | Refactoring means (re)organizing your code **without modifying its original functionality**. Refactoring is the process of making **small** changes or adjustments to your code without affecting or changing how the code functions while in use. 17 | 18 | ## Benefits of refactoring 19 | 20 | ### It helps improve structure and coherence 21 | Refactoring helps you **improve the design** of your software. Developing applications is a difficult task. As you add additional functions, the relevance of your design may be affected. Then, abstractions are no longer as pure as they once were. 22 | 23 | #### Example 24 | 25 | > We started with a `Bird` class which contains a `fly()` method. From it we derived the `Swan`, `Eagle` and the `Dove` type. All works fine, but then a `Pinguin` enters the scence, followed by a `Kiwi` and an `Ostrich`. So the `fly()` method needs to moved to adjust for the latter type of birds. It's a general rule that we will encounter stuff we did not account for. 26 | 27 | You can improve the structure and coherence of your programs by refactoring your code **regularly**. 28 | 29 | ### It gives a better understanding of the code 30 | If you refactor properly, your code will be more easily understandable afterwards. Your code will also be easier to understand by improving the design. 31 | 32 | #### Example 33 | 34 | > If you find pieces of code where you need to do a lot of "pointer chasing" it is generally a good idea to refactor the code. Same is true for a lot of functions calling each other to model simple functionality. Chasing functions and pointers makes your code hard to understand. 35 | 36 | It is common knowledge that developers read code far more frequently than they write it. As a result, it's in your best interest to keep things as simple as possible, which considerably improves maintainability. Also, people who read it in the future will be grateful. 37 | 38 | ### Refactoring broadens your knowledge 39 | Finally, refactoring is a method of **active learning**. Even if you didn't write the code, refactoring it gives you a better grasp of what it does. And by reading the code of your collegues you will learn other possible ways to write code and absorb good practices. 40 | 41 | **Warning** 42 | > It may be tempting to show-off your skills and impress your collegues by introducing "superstar code". Don't do that or you'll enter into an arms race and the readability of your code spirals out of control. Again: keep things as simple as possible. 43 | 44 | ## Quick discussion 45 | Briefly share your experiences with refactoring during Project B. -------------------------------------------------------------------------------- /Workshop - Refactoring/04_tools.md: -------------------------------------------------------------------------------- 1 | # Refactoring and IDE Support 2 | Because refactoring is so important all modern Integrated Developer Environments (IDEs) have refactor capabilities built-in or have plugins available. Here we will explore the refactoring capabilities of Visual Studio Code (VSCode). We assume you have the **Python** and **Pylance** plugins installed. 3 | 4 | ## Renaming functions and variables 5 | VSCode makes renaming functions and variables extremely easy. 6 | 7 | ### Preparation 8 | Open a new VSCode window (`File > New Window`) and open the folder `tools-example`. The example files contain multiple typos, which we want to correct. 9 | 10 | ### Rename strategy 11 | We have to correct variable names, function names, text in comments and text in strings. For fixing typos we have two methods to our disposal: 12 | 13 | - Rename symbol 14 | - Find & replace 15 | 16 | Our strategy is first to rename our functions, then our variables and lastly strings and comments. 17 | 18 | ### Rename symbol 19 | Let's start with `rename symbol`. To show the power of this feature, turn the `printString()` function into camel casing. 20 | 21 | Select the function name and press `F2`. This let's us rename the function over the **entire** code base. Any reference to this function will be renamed. 22 | 23 | Let's also rename the misspelled `nam` variable. 24 | 25 | **Limitation** 26 | > You cannot globally rename comments. Try it. 27 | 28 | **Warning** 29 | > You cannot rename built-in class methods (try renaming the `Dict.strip()` method), but be aware that you *can* rename functions and methods in the standard modules. 30 | > 31 | > Try renaming the `random.choices()` function and check that it is indeed changes in the random module. And change it back to its original form to prevent problems in other code that depends on the random module. 32 | 33 | ### Find & replace 34 | With our variables and functions renamed, we can now safely rename our strings and comments. Here we have two options: 35 | 36 | 1. Use `ctrl or cmd` + `shift` + `f` to find & replace inside a single file 37 | 2. Use `ctrl or cmd` + `shift` + `h` to find & replace inside all files 38 | 39 | Since both files contain a misspelled 'nam' in the comments, we use `ctrl or cmd` + `shift` + `h`. 40 | 41 | **Tip** 42 | > Never ever rename function or variable names by hand. Not only is it slower, you might also introduce typo's and thereby bugs. 43 | 44 | ## Extracting functions 45 | Another useful feature is the `extract into` functionality. 46 | 47 | To show how this works you need to select the code you want to convert into a function. If we look at the `process_user_data()` function than we see that this is a good candidate for refactoring. So let's refactor this function by splitting it up in multiple, smaller functions. 48 | 49 | 1. Select the code block below: 50 | 51 | ```python 52 | name = user_data['name'] 53 | if not isinstance(name, str) or not name.strip(): 54 | raise ValueError("Invalid name") 55 | name = nam.strip().title() 56 | ``` 57 | 2. Use `ctrl` + `shift` + `r` to extract the function 58 | 59 | 3. Rename the assigned function name `jls_extract_def` to `process_name` 60 | 61 | Repeat the steps above for the code below the comments: 62 | 63 | - Process age 64 | - Process email 65 | - Save to database (simulated) 66 | 67 | > Congratulations: you've mastered some very basic but powerful refactoring techniques. -------------------------------------------------------------------------------- /Workshop - Refactoring/06_resources.md: -------------------------------------------------------------------------------- 1 | # References and Further reading 2 | 3 | This workshop is only an introduction. Here you find more in-depth information, but you are encouraged to dig in further. 4 | 5 | ## Refactoring 6 | 7 | - [Wikipedia](https://en.wikipedia.org/wiki/Code_refactoring) 8 | - [Refactoring Guru](https://refactoring.guru/refactoring) 9 | - [What is Refactoring, and why is it so important?](https://www.youtube.com/watch?v=PGjrn9Ci2aY) 10 | - [Code Refactoring Best Practices](https://www.freecodecamp.org/news/best-practices-for-refactoring-code) 11 | - [Techniques, Tools, and Best Practices](https://www.codesee.io/learning-center/python-refactoring) 12 | - [Refactoring Workshop](https://github.com/benchristel/refactoring-workshop) 13 | - [Red-Green-Refactor method](https://www.youtube.com/watch?v=fx-Ne_s71iY) 14 | - [Clean Code Is Killing Your Projects](https://www.youtube.com/watch?v=1uzlBSL7-UM) 15 | 16 | ## Documentation generation 17 | 18 | - [How to generate documentation from python doc strings](https://www.youtube.com/watch?v=BWIrhgCAae0) 19 | 20 | ## Code conventions 21 | 22 | - [How to Write Beautiful Python Code With PEP 8](https://realpython.com/python-pep8) 23 | 24 | ## Design Patterns 25 | 26 | - [Wikipedia](https://en.wikipedia.org/wiki/Design_Patterns) 27 | - [Design Patterns 101](https://medium.com/@digicore/software-design-patterns-101-a-beginners-guide-c6860ef8bb63) 28 | - [Design Patterns Guru](https://refactoring.guru/design-patterns) 29 | - [Coursera](https://www.coursera.org/learn/design-patterns) -------------------------------------------------------------------------------- /Workshop - Refactoring/sphinx-example/.DS_Store: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Refactoring/sphinx-example/.DS_Store -------------------------------------------------------------------------------- /Workshop - Refactoring/sphinx-example/docs/Calculator.rst: -------------------------------------------------------------------------------- 1 | Calculator module 2 | ================= 3 | 4 | .. automodule:: calculator.Calculator 5 | :members: 6 | :undoc-members: 7 | :show-inheritance: 8 | -------------------------------------------------------------------------------- /Workshop - Refactoring/sphinx-example/docs/Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line, and also 5 | # from the environment for the first two. 6 | SPHINXOPTS ?= 7 | SPHINXBUILD ?= sphinx-build 8 | SOURCEDIR = . 9 | BUILDDIR = _build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile 16 | 17 | # Catch-all target: route all unknown targets to Sphinx using the new 18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 19 | %: Makefile 20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 21 | -------------------------------------------------------------------------------- /Workshop - Refactoring/sphinx-example/docs/_build/.DS_Store: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Refactoring/sphinx-example/docs/_build/.DS_Store -------------------------------------------------------------------------------- /Workshop - Refactoring/sphinx-example/docs/_build/doctrees/Calculator.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Refactoring/sphinx-example/docs/_build/doctrees/Calculator.doctree -------------------------------------------------------------------------------- /Workshop - Refactoring/sphinx-example/docs/_build/doctrees/environment.pickle: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Refactoring/sphinx-example/docs/_build/doctrees/environment.pickle -------------------------------------------------------------------------------- /Workshop - Refactoring/sphinx-example/docs/_build/doctrees/index.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Refactoring/sphinx-example/docs/_build/doctrees/index.doctree -------------------------------------------------------------------------------- /Workshop - Refactoring/sphinx-example/docs/_build/doctrees/modules.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Refactoring/sphinx-example/docs/_build/doctrees/modules.doctree -------------------------------------------------------------------------------- /Workshop - Refactoring/sphinx-example/docs/_build/html/.buildinfo: -------------------------------------------------------------------------------- 1 | # Sphinx build info version 1 2 | # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. 3 | config: 3cff2f7158fb95a5895456a646ad31c5 4 | tags: 645f666f9bcd5a90fca523b33c5a78b7 5 | -------------------------------------------------------------------------------- /Workshop - Refactoring/sphinx-example/docs/_build/html/_modules/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 |
26 |
86 |
94 |
95 |
96 |
97 |
98 |
99 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/_sources/Calculator.rst.txt:
--------------------------------------------------------------------------------
1 | Calculator module
2 | =================
3 |
4 | .. automodule:: calculator.Calculator
5 | :members:
6 | :undoc-members:
7 | :show-inheritance:
8 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/_sources/index.rst.txt:
--------------------------------------------------------------------------------
1 | .. Calculator documentation master file, created by
2 | sphinx-quickstart on Mon May 27 13:32:03 2024.
3 | You can adapt this file completely to your liking, but it should at least
4 | contain the root `toctree` directive.
5 |
6 | Welcome to Calculator's documentation!
7 | ======================================
8 |
9 | .. toctree::
10 | :maxdepth: 2
11 | :caption: Contents:
12 |
13 | modules
14 |
15 | Indices and tables
16 | ==================
17 |
18 | * :ref:`genindex`
19 | * :ref:`modindex`
20 | * :ref:`search`
21 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/_sources/modules.rst.txt:
--------------------------------------------------------------------------------
1 | src
2 | ===
3 |
4 | .. toctree::
5 | :maxdepth: 4
6 |
7 | Calculator
8 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/_static/custom.css:
--------------------------------------------------------------------------------
1 | /* This file intentionally left blank. */
2 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/_static/doctools.js:
--------------------------------------------------------------------------------
1 | /*
2 | * doctools.js
3 | * ~~~~~~~~~~~
4 | *
5 | * Base JavaScript utilities for all Sphinx HTML documentation.
6 | *
7 | * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
8 | * :license: BSD, see LICENSE for details.
9 | *
10 | */
11 | "use strict";
12 |
13 | const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([
14 | "TEXTAREA",
15 | "INPUT",
16 | "SELECT",
17 | "BUTTON",
18 | ]);
19 |
20 | const _ready = (callback) => {
21 | if (document.readyState !== "loading") {
22 | callback();
23 | } else {
24 | document.addEventListener("DOMContentLoaded", callback);
25 | }
26 | };
27 |
28 | /**
29 | * Small JavaScript module for the documentation.
30 | */
31 | const Documentation = {
32 | init: () => {
33 | Documentation.initDomainIndexTable();
34 | Documentation.initOnKeyListeners();
35 | },
36 |
37 | /**
38 | * i18n support
39 | */
40 | TRANSLATIONS: {},
41 | PLURAL_EXPR: (n) => (n === 1 ? 0 : 1),
42 | LOCALE: "unknown",
43 |
44 | // gettext and ngettext don't access this so that the functions
45 | // can safely bound to a different name (_ = Documentation.gettext)
46 | gettext: (string) => {
47 | const translated = Documentation.TRANSLATIONS[string];
48 | switch (typeof translated) {
49 | case "undefined":
50 | return string; // no translation
51 | case "string":
52 | return translated; // translation exists
53 | default:
54 | return translated[0]; // (singular, plural) translation tuple exists
55 | }
56 | },
57 |
58 | ngettext: (singular, plural, n) => {
59 | const translated = Documentation.TRANSLATIONS[singular];
60 | if (typeof translated !== "undefined")
61 | return translated[Documentation.PLURAL_EXPR(n)];
62 | return n === 1 ? singular : plural;
63 | },
64 |
65 | addTranslations: (catalog) => {
66 | Object.assign(Documentation.TRANSLATIONS, catalog.messages);
67 | Documentation.PLURAL_EXPR = new Function(
68 | "n",
69 | `return (${catalog.plural_expr})`
70 | );
71 | Documentation.LOCALE = catalog.locale;
72 | },
73 |
74 | /**
75 | * helper function to focus on search bar
76 | */
77 | focusSearchBar: () => {
78 | document.querySelectorAll("input[name=q]")[0]?.focus();
79 | },
80 |
81 | /**
82 | * Initialise the domain index toggle buttons
83 | */
84 | initDomainIndexTable: () => {
85 | const toggler = (el) => {
86 | const idNumber = el.id.substr(7);
87 | const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`);
88 | if (el.src.substr(-9) === "minus.png") {
89 | el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`;
90 | toggledRows.forEach((el) => (el.style.display = "none"));
91 | } else {
92 | el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`;
93 | toggledRows.forEach((el) => (el.style.display = ""));
94 | }
95 | };
96 |
97 | const togglerElements = document.querySelectorAll("img.toggler");
98 | togglerElements.forEach((el) =>
99 | el.addEventListener("click", (event) => toggler(event.currentTarget))
100 | );
101 | togglerElements.forEach((el) => (el.style.display = ""));
102 | if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler);
103 | },
104 |
105 | initOnKeyListeners: () => {
106 | // only install a listener if it is really needed
107 | if (
108 | !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS &&
109 | !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
110 | )
111 | return;
112 |
113 | document.addEventListener("keydown", (event) => {
114 | // bail for input elements
115 | if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
116 | // bail with special keys
117 | if (event.altKey || event.ctrlKey || event.metaKey) return;
118 |
119 | if (!event.shiftKey) {
120 | switch (event.key) {
121 | case "ArrowLeft":
122 | if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
123 |
124 | const prevLink = document.querySelector('link[rel="prev"]');
125 | if (prevLink && prevLink.href) {
126 | window.location.href = prevLink.href;
127 | event.preventDefault();
128 | }
129 | break;
130 | case "ArrowRight":
131 | if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
132 |
133 | const nextLink = document.querySelector('link[rel="next"]');
134 | if (nextLink && nextLink.href) {
135 | window.location.href = nextLink.href;
136 | event.preventDefault();
137 | }
138 | break;
139 | }
140 | }
141 |
142 | // some keyboard layouts may need Shift to get /
143 | switch (event.key) {
144 | case "/":
145 | if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
146 | Documentation.focusSearchBar();
147 | event.preventDefault();
148 | }
149 | });
150 | },
151 | };
152 |
153 | // quick alias for translations
154 | const _ = Documentation.gettext;
155 |
156 | _ready(Documentation.init);
157 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/_static/documentation_options.js:
--------------------------------------------------------------------------------
1 | const DOCUMENTATION_OPTIONS = {
2 | VERSION: '0.0.0',
3 | LANGUAGE: 'en',
4 | COLLAPSE_INDEX: false,
5 | BUILDER: 'html',
6 | FILE_SUFFIX: '.html',
7 | LINK_SUFFIX: '.html',
8 | HAS_SOURCE: true,
9 | SOURCELINK_SUFFIX: '.txt',
10 | NAVIGATION_WITH_KEYS: false,
11 | SHOW_SEARCH_SUMMARY: true,
12 | ENABLE_SEARCH_SHORTCUTS: true,
13 | };
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/_static/file.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Refactoring/sphinx-example/docs/_build/html/_static/file.png
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/_static/minus.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Refactoring/sphinx-example/docs/_build/html/_static/minus.png
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/_static/plus.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Refactoring/sphinx-example/docs/_build/html/_static/plus.png
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/genindex.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
27 |
40 |
84 |
85 |
28 |
29 |
30 |
39 |
31 |
32 |
37 |
38 |
26 |
153 |
161 |
162 |
163 |
164 |
165 |
166 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
27 |
107 |
151 |
152 |
28 |
29 |
30 |
106 |
31 |
32 |
33 |
50 |
51 |
67 |
68 |
75 |
76 |
92 |
93 |
100 |
101 |
102 |
103 |
104 |
105 | Index
34 | 35 | 43 |A
44 |
|
49 |
C
52 |
|
57 |
|
66 |
D
69 |
|
74 |
M
77 |
|
87 |
|
91 |
S
94 |
|
99 |
28 |
107 |
118 |
119 |
120 |
121 |
122 |
123 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/modules.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
29 |
60 |
105 |
106 |
30 |
31 |
32 |
59 |
33 |
34 |
35 |
46 |
47 |
54 |
55 |
56 |
57 |
58 | Welcome to Calculator’s documentation!¶
36 |
37 |
45 | Contents:
38 |-
39 |
- src
-
40 |
- Calculator module 41 |
43 |
Indices and tables¶
48 |-
49 |
- 50 |
- 51 |
- 52 |
29 |
109 |
120 |
121 |
122 |
123 |
124 |
125 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/objects.inv:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Refactoring/sphinx-example/docs/_build/html/objects.inv
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/py-modindex.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
30 |
58 |
107 |
108 |
31 |
32 |
33 |
57 |
34 |
35 |
36 |
52 |
53 |
54 |
55 |
56 | src¶
37 |
38 |
51 | -
39 |
- Calculator module
-
40 |
Calculator-
41 |
Calculator.add()
42 | Calculator.divide()
43 | Calculator.multiply()
44 | Calculator.subtract()
45 |
47 |
49 |
29 |
110 |
118 |
119 |
120 |
121 |
122 |
123 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/search.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
30 |
64 |
108 |
109 |
31 |
32 |
33 |
63 |
34 |
35 |
36 |
43 |
58 |
59 |
60 |
61 |
62 | Python Module Index
37 | 38 |
39 | c
40 |
41 |
42 | | 45 | c | ||
| 49 | |
50 | calculator | 51 | |
| 54 | |
55 | calculator.Calculator | 56 | |
33 |
107 |
115 |
116 |
117 |
118 |
119 |
120 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/_build/html/searchindex.js:
--------------------------------------------------------------------------------
1 | Search.setIndex({"alltitles": {"Calculator module": [[0, "module-calculator.Calculator"]], "Contents:": [[1, null]], "Indices and tables": [[1, "indices-and-tables"]], "Welcome to Calculator\u2019s documentation!": [[1, "welcome-to-calculator-s-documentation"]], "src": [[2, "src"]]}, "docnames": ["Calculator", "index", "modules"], "envversion": {"sphinx": 61, "sphinx.domains.c": 3, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 9, "sphinx.domains.index": 1, "sphinx.domains.javascript": 3, "sphinx.domains.math": 2, "sphinx.domains.python": 4, "sphinx.domains.rst": 2, "sphinx.domains.std": 2, "sphinx.ext.viewcode": 1}, "filenames": ["Calculator.rst", "index.rst", "modules.rst"], "indexentries": {"add() (calculator.calculator.calculator method)": [[0, "calculator.Calculator.Calculator.add", false]], "calculator (class in calculator.calculator)": [[0, "calculator.Calculator.Calculator", false]], "calculator.calculator": [[0, "module-calculator.Calculator", false]], "divide() (calculator.calculator.calculator method)": [[0, "calculator.Calculator.Calculator.divide", false]], "module": [[0, "module-calculator.Calculator", false]], "multiply() (calculator.calculator.calculator method)": [[0, "calculator.Calculator.Calculator.multiply", false]], "subtract() (calculator.calculator.calculator method)": [[0, "calculator.Calculator.Calculator.subtract", false]]}, "objects": {"calculator": [[0, 0, 0, "-", "Calculator"]], "calculator.Calculator": [[0, 1, 1, "", "Calculator"]], "calculator.Calculator.Calculator": [[0, 2, 1, "", "add"], [0, 2, 1, "", "divide"], [0, 2, 1, "", "multiply"], [0, 2, 1, "", "subtract"]]}, "objnames": {"0": ["py", "module", "Python module"], "1": ["py", "class", "Python class"], "2": ["py", "method", "Python method"]}, "objtypes": {"0": "py:module", "1": "py:class", "2": "py:method"}, "terms": {"A": 0, "If": 0, "The": 0, "add": [0, 2], "anoth": 0, "arithmet": 0, "b": 0, "base": 0, "basic": 0, "between": 0, "calcul": 2, "class": 0, "denomin": 0, "differ": 0, "divid": [0, 2], "first": 0, "float": 0, "from": 0, "i": 0, "index": 1, "method": 0, "modul": [1, 2], "multipli": [0, 2], "number": 0, "numer": 0, "object": 0, "one": 0, "oper": 0, "page": 1, "paramet": 0, "perform": 0, "product": 0, "provid": 0, "quotient": 0, "rais": 0, "return": 0, "search": 1, "second": 0, "simpl": 0, "sourc": 0, "src": 1, "subtract": [0, 2], "sum": 0, "thi": 0, "two": 0, "type": 0, "zero": 0, "zerodivisionerror": 0}, "titles": ["Calculator module", "Welcome to Calculator\u2019s documentation!", "src"], "titleterms": {"": 1, "calcul": [0, 1], "content": 1, "document": 1, "indic": 1, "modul": 0, "src": 2, "tabl": 1, "welcom": 1}})
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/conf.py:
--------------------------------------------------------------------------------
1 | # Configuration file for the Sphinx documentation builder.
2 | #
3 | # For the full list of built-in configuration values, see the documentation:
4 | # https://www.sphinx-doc.org/en/master/usage/configuration.html
5 |
6 | # -- Project information -----------------------------------------------------
7 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8 |
9 | import os
10 | import sys
11 |
12 | sys.path.insert(0, os.path.abspath('../src'))
13 |
14 | project = 'Calculator'
15 | copyright = '2024'
16 | author = 'hoofr'
17 | release = '0.0.0'
18 |
19 | # -- General configuration ---------------------------------------------------
20 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
21 |
22 | extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
23 |
24 | templates_path = ['_templates']
25 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
26 |
27 |
28 |
29 | # -- Options for HTML output -------------------------------------------------
30 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
31 |
32 | html_theme = 'alabaster'
33 | html_static_path = ['_static']
34 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/index.rst:
--------------------------------------------------------------------------------
1 | .. Calculator documentation master file, created by
2 | sphinx-quickstart on Mon May 27 13:32:03 2024.
3 | You can adapt this file completely to your liking, but it should at least
4 | contain the root `toctree` directive.
5 |
6 | Welcome to Calculator's documentation!
7 | ======================================
8 |
9 | .. toctree::
10 | :maxdepth: 2
11 | :caption: Contents:
12 |
13 | modules
14 |
15 | Indices and tables
16 | ==================
17 |
18 | * :ref:`genindex`
19 | * :ref:`modindex`
20 | * :ref:`search`
21 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/make.bat:
--------------------------------------------------------------------------------
1 | @ECHO OFF
2 |
3 | pushd %~dp0
4 |
5 | REM Command file for Sphinx documentation
6 |
7 | if "%SPHINXBUILD%" == "" (
8 | set SPHINXBUILD=sphinx-build
9 | )
10 | set SOURCEDIR=.
11 | set BUILDDIR=_build
12 |
13 | %SPHINXBUILD% >NUL 2>NUL
14 | if errorlevel 9009 (
15 | echo.
16 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17 | echo.installed, then set the SPHINXBUILD environment variable to point
18 | echo.to the full path of the 'sphinx-build' executable. Alternatively you
19 | echo.may add the Sphinx directory to PATH.
20 | echo.
21 | echo.If you don't have Sphinx installed, grab it from
22 | echo.https://www.sphinx-doc.org/
23 | exit /b 1
24 | )
25 |
26 | if "%1" == "" goto help
27 |
28 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29 | goto end
30 |
31 | :help
32 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33 |
34 | :end
35 | popd
36 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/docs/modules.rst:
--------------------------------------------------------------------------------
1 | src
2 | ===
3 |
4 | .. toctree::
5 | :maxdepth: 4
6 |
7 | Calculator
8 |
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/src/calculator/Calculator.py:
--------------------------------------------------------------------------------
1 | # src/calculator.py
2 |
3 | class Calculator:
4 | """
5 | A simple calculator class to perform basic arithmetic operations.
6 |
7 | This class provides methods to add, subtract, multiply, and divide two numbers.
8 | """
9 |
10 | def add(self, a, b):
11 | """
12 | Add two numbers.
13 |
14 | :param a: The first number.
15 | :type a: float
16 | :param b: The second number.
17 | :type b: float
18 | :return: The sum of a and b.
19 | :rtype: float
20 | """
21 | return a + b
22 |
23 | def subtract(self, a, b):
24 | """
25 | Subtract one number from another.
26 |
27 | :param a: The number to be subtracted from.
28 | :type a: float
29 | :param b: The number to subtract.
30 | :type b: float
31 | :return: The difference between a and b.
32 | :rtype: float
33 | """
34 | return a - b
35 |
36 | def multiply(self, a, b):
37 | """
38 | Multiply two numbers.
39 |
40 | :param a: The first number.
41 | :type a: float
42 | :param b: The second number.
43 | :type b: float
44 | :return: The product of a and b.
45 | :rtype: float
46 | """
47 | return a * b
48 |
49 | def divide(self, a, b):
50 | """
51 | Divide one number by another.
52 |
53 | :param a: The numerator.
54 | :type a: float
55 | :param b: The denominator.
56 | :type b: float
57 | :return: The quotient of a divided by b.
58 | :rtype: float
59 | :raises ZeroDivisionError: If b is zero.
60 | """
61 | if b == 0:
62 | raise ZeroDivisionError("The denominator b cannot be zero.")
63 | return a / b
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/src/calculator/__init__.py:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Refactoring/sphinx-example/src/calculator/__init__.py
--------------------------------------------------------------------------------
/Workshop - Refactoring/sphinx-example/workshop.md:
--------------------------------------------------------------------------------
1 | # Spinx documentation
2 | Here you find the steps to generate documentation from the docstring in the code.
3 |
4 | ## Prerequisites
5 |
6 | ### Install Sphinx
7 | `pip install sphinx`
8 |
9 | ## Setup
10 | We have already setup the config to speed up the workshop. If you want to do it yourself you must run `sphinx-quickstart` first and then consult the resources for some tutorials.
11 |
12 | ## Generation
13 |
14 | ### 1. Enter the project folder
15 | `cd sphinx-example`
16 |
17 | ### 2. Check the Calculator docstrings
18 | Open the `Calculator` class and see how we have added the docstring.
19 |
20 | ## 3. Generate the documentation
21 | - Make sure you are in the root of the `sphinx-example` folder
22 | - Now run `sphinx-apidoc -o ./docs ./src/` to generate the docs
23 |
24 | ## 4. View the documentation
25 | Find the index.html and open it in your browser.
26 |
27 | ## 5. Extend the documentation
28 | - Play around in the Calculator class, add some new methods
29 | - Add a new module or class and see what it does to your docs
30 |
31 | ## 6. Apply to CargoHub API
32 | Use the `sphinx-example` as a template for your CargoHub API code and start documenting your code base.
--------------------------------------------------------------------------------
/Workshop - Refactoring/tools-example/main.py:
--------------------------------------------------------------------------------
1 | import random
2 | import string
3 |
4 | from mod import printString
5 |
6 | def process_user_data(user_data):
7 | # Validate user data
8 | if not isinstance(user_data, dict):
9 | raise ValueError("Invalid data format")
10 | if 'nam' not in user_data or 'age' not in user_data or 'email' not in user_data:
11 | raise ValueError("Missing required fields")
12 |
13 | # Process nam
14 | nam = user_data['nam']
15 | if not isinstance(nam, str) or not nam.strip():
16 | raise ValueError("Invalid nam")
17 | nam = nam.strip().title()
18 |
19 | # Process age
20 | age = user_data['age']
21 | if not isinstance(age, int) or age <= 0:
22 | raise ValueError("Invalid age")
23 |
24 | # Process email
25 | email = user_data['email']
26 | if not isinstance(email, str) or '@' not in email:
27 | raise ValueError("Invalid email")
28 | email = email.lower()
29 |
30 | # Generate user ID
31 | user_id = ''.join(random.choices(string.ascii_letters + string.digits, k=8))
32 |
33 | # Save to database (simulated)
34 | database = []
35 | database.append({
36 | 'user_id': user_id,
37 | 'nam': nam,
38 | 'age': age,
39 | 'email': email
40 | })
41 |
42 | return user_id
43 |
44 | def main():
45 | printString("Program starting...")
46 | print("Welcome to the User Data Processing Program!")
47 | print("Please provide the following details:")
48 | nam = input("nam: ")
49 | age = int(input("Age: "))
50 | email = input("Email: ")
51 |
52 | user_data = {
53 | 'nam': nam,
54 | 'age': age,
55 | 'email': email
56 | }
57 |
58 | try:
59 | user_id = process_user_data(user_data)
60 | print("User data processed successfully.")
61 | print("User ID:", user_id)
62 | except ValueError as e:
63 | print("Error processing user data:", e)
64 |
65 | printString("Program ended.")
66 |
67 | if __name__ == "__main__":
68 | main()
--------------------------------------------------------------------------------
/Workshop - Refactoring/tools-example/mod.py:
--------------------------------------------------------------------------------
1 | def printString(s):
2 | # A misspelled 'nam' here to demonstrate
3 | # the find & replace in files feature
4 | print(s)
--------------------------------------------------------------------------------
/Workshop - Requirements Specification/01_introduction.md:
--------------------------------------------------------------------------------
1 | # Introduction
2 | In this workshop you will learn about requirements, how to collect them and how to write them down. To be able to document the requirements for the CargoHub API we need to develop a basic understanding of RESTful APIs and how to read them. That's why RESTful API reading practice is included in this workshop. But first: requirements.
3 |
4 | ## Objectives:
5 | - Understand the principles of REST and its application in software development.
6 | - Learn how to gather, analyze, and document software requirements.
7 | - Apply REST principles to design and implement a simple RESTful API.
8 | - Integrate software requirements into the development process.
9 | - Retrieve requirements from existing, undocumented software.
10 |
11 | ## Why requirements?
12 | Well, try to build something with just a *single* requirement:
13 |
14 | - We need a bridge to cross over
15 |
16 | ### Activity
17 | Suppose you are tasked to build this bridge. How would you proceed?
18 |
19 | Take some time to write down your strategy.
20 |
21 | ### Possible answer
22 | First you need to recognize that this requirement is not very helpful. You need more information to proceed. For example: where should the bridge be build? Is it to cross a river or a road? From that you could derive how long the bridge would need to be. You should also need to know if the bridge is for pedestrians, for cyclist and/or for cars. This determines the strength, the width and the material, which in turn determines the costs of the bridge. Etcetera.
23 |
24 | > Without requirements we don't know *what* to build and, as a result, *how* to build it.
25 |
26 | Notice the difference between **what** and **how**:
27 |
28 | - Requirements are about *what* to build
29 | - Design is about *how* to build it
30 |
31 | The design (of the system, user experience and interface) always *follows* from the requirements. Given the time, money and resources, it is the task of the (software) engineer to come up with an optimal solution that fits the requirements.
32 |
33 | > Engineering is about building an optimal solution. Every decision you make will be about juggling multiple requirements.
34 |
35 | ## Requirement gathering
36 | Going back to the bridge building example: the asking for clarity is the process of gathering requirements.
37 |
38 | > During the project the technical teacher knows about the details and it is up to you to ask for clarification.
39 |
40 | In reality we start with more than one requirement and during the gathering phase we try te refine the demands and needs such that we can build the right thing.
41 |
42 | Speaking of the 'right thing':
43 |
44 | - Good **requirements** ensure that we build *the right thing*
45 | - Good **design** ensures that that we build *the thing right*
46 |
47 | It really depends on the experience of the team and the complexity & nature of the project which requirments need be known up front, and which can be left to be refined during the project.
48 |
49 | ### Activity
50 | Try to explain what the items below have in common and what makes them different:
51 |
52 | - Building a chair
53 | - Building an airplane
54 | - Building a thesis evaluation tool for teachers
55 |
56 | ### Possible answers
57 | Although a chair and airplane differ in complexity, their goal is pretty clear. Given the constraints (size, speed, weight, ...), one could start planning the construction process pretty soon: we can adopt a waterfall process.
58 |
59 | This cannot be said about the thesis evaluation tool. What should it even do? Here we need to do a lot of research up front and adjusting during the process to build the right thing: we should choose for an agile approach.
60 |
61 | - With *lots of unknows* an **agile approach** may be preferred
62 | - With *little unknowns* a **waterfall method** may be preferred
63 |
64 | ### Activity
65 | Reading the course manual, what would be a good approach for this project for your team?
66 |
67 | ## Summary
68 | We need requirements else we don't know what to build.
69 |
70 | In the next chapter we will look at different types of requirements.
--------------------------------------------------------------------------------
/Workshop - Requirements Specification/04_combining.md:
--------------------------------------------------------------------------------
1 | # Combining REST and Requirements
2 | Now we have a basic understanding of RESTful APIs and requirements, let's combine the two.
3 |
4 | ### Question
5 | Looking back at the different types of requirements, which types apply to APIs?
6 |
7 | Choose from:
8 |
9 | - Business requirements
10 | - User requirements
11 | - Functional requirements
12 | - Non-functional requirements
13 |
14 | ### Answer
15 | In short: they all apply.
16 |
17 | You might think that user requirements don't apply to APIs. Even though we do not directly interact with the end users, the actual users of our API are our collegue developers.
18 |
19 | ### Question
20 | What should they need to be able to work with our API?
21 |
22 | ### Answer
23 | Indeed: good documentation. It is your teams goal to provide good documentation of the CargoHub API during this project.
24 |
25 | ## Mapping Requirements to RESTful API Design
26 | During the project you get an existing API code base and it is your task to reverse engineer the functional requirements it implements.
27 |
28 | ### Question
29 | Given the endpoints below, what kind of app does this RESTful API represent?
30 |
31 | - `https://api.app.com/lists`
32 | - `https://api.app.com/members`
33 | - `https://api.app.com/lists/tasks`
34 | - `https://api.app.com/lists/tasks/members`
35 |
36 | ### Answer
37 | It could be the API of a collaborative to-do app.
38 |
39 | ### Question
40 | The direct users of our API are the developers that need to implement the app. They require that:
41 |
42 | - The API should be easy to understand
43 | - The API should be easy to work with
44 |
45 | Does the endpoint description satisfy this demand?
46 |
47 | ### Answer
48 | Not really. It does describe which resources there are and how they relate, but this is not enough to work with this API. For example: it is not clear what properties a member has and how to update those.
49 |
50 | ### Question
51 | What functional requirements can you deduce from the endpoints and the fact that the API exposes the logic of a collaborative to-do app?
52 |
53 | ### Possible Answer
54 | It's a to-do app so the API should support:
55 |
56 | - Creating a to-do list
57 | - Changing the name of a to-do list
58 | - Remove a to-do list
59 | - Listing the to-do lists
60 | - Adding tasks to a to-do list
61 | - Checking tasks from a to-do list
62 | - Removing tasks from the to-do lists
63 |
64 | Since it is a collaborative to-do list, the API should also support:
65 |
66 | - Inviting new members
67 | - Coupling one or more members to a certain task
68 | - Showing the members attached to a task
69 | - Removing members from a certain task
70 |
71 | ### Question
72 | Can you deduce any non-functional requirement from the information above?
73 |
74 | ### Answer
75 | Not really. It is clear that it is a collaborative to-do app, but it is not clear how many concurrent members the app should support. It is further clear that the API should be well described for our collegue developers, but nothing is mentioned about the code base itself. Are we expected to document our code? Etcetera.
76 |
77 | ## Conclusion
78 | In this lesson we have deduced some basic requirements from endpoint only. It is your task to reverse engineer all requirements from the CargoHub code base. To help you document your reseach we end with some structure, tips and tricks.
--------------------------------------------------------------------------------
/Workshop - Requirements Specification/06_resources.md:
--------------------------------------------------------------------------------
1 | ## Requirements
2 | - [Waterfall versus Agile](https://www.youtube.com/watch?v=XP4o0ArkP4s)
3 | - [Types of requirements](https://www.techtarget.com/searchsoftwarequality/answer/What-are-requirements-types)
4 | - [Functional requirements](https://en.wikipedia.org/wiki/Functional_requirement)
5 | - [Non-functional requirements](https://en.wikipedia.org/wiki/Non-functional_requirement)
6 |
7 | ## REST
8 | - [HTTP protocol](https://developer.mozilla.org/en-US/docs/Web/HTTP)
9 | - [HTTP messages](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages)
10 | - [REST versus RPC](https://www.geeksforgeeks.org/difference-between-rest-api-and-rpc-api)
11 | - [REST Explainer](https://www.youtube.com/watch?v=6sUbt-Qp6Pg)
12 | - [Uniform Resource Identifier](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier)
13 | - [Uniform Resource Locator](https://en.wikipedia.org/wiki/URL)
14 |
15 | ## Hoppscotch
16 | - [API explorer](https://hoppscotch.io)
17 | - [Connect to localhost](https://github.com/hoppscotch/hoppscotch-extension)
18 |
19 | ## API & requirements
20 | - [Functional and non-functional](https://www.akana.com/blog/api-requirements-what-consider)
21 | - [How to build an API](https://blog.postman.com/how-to-build-an-api)
22 |
23 | ## Requirements specification
24 | - [Checklist with Examples](https://medium.com/@growsolutions/functional-and-non-functional-requirements-the-ultimate-checklist-with-examples-cde16aba33d7)
25 | - [Hire good writers](https://basecamp.com/gettingreal/08.6-wordsmiths)
--------------------------------------------------------------------------------
/Workshop - Requirements Specification/images/smile-32.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/hogeschool/Software-Construction/2e068e69e050ab9f885e1dae623a937fd4b95293/Workshop - Requirements Specification/images/smile-32.png
--------------------------------------------------------------------------------
/Workshop - Software Testing/03_automation.md:
--------------------------------------------------------------------------------
1 | # Automating tests
2 | Automated testing is a crucial practice in software development. It helps ensure the quality, reliability, and correctness of your codebase. Let’s explore some key aspects related to automating tests.
3 |
4 |
34 |
71 |
105 |
106 |
35 |
36 |
37 |
70 |
38 |
39 |
68 |
69 | Search
40 | 41 | 49 | 50 | 51 |52 | Searching for multiple words only shows matches that contain 53 | all words. 54 |
55 | 56 | 57 | 62 | 63 | 64 | 65 | 66 | 67 |5 | 6 | ## Tools 7 | 8 | ### Pytest 9 | Pytest is a popular testing framework for Python. It provides a simple and efficient way to write and execute test cases. Some of its features include: 10 | 11 | - **Concise Syntax**: Pytest allows you to write test functions using a clean and readable syntax. You can use plain Python assert statements or more advanced assertions. 12 | - **Fixture Support**: Fixtures allow you to set up and tear down resources needed for testing (e.g., database connections, mock services). Pytest makes it easy to define and use fixtures. 13 | - **Powerful Test Discovery**: Pytest automatically discovers and runs all test files in your project directory. No need to explicitly specify test paths. 14 | - **Plugins**: Pytest has a rich ecosystem of plugins that extend its functionality. You can find plugins for coverage reporting, parallel test execution, and more. 15 | 16 | If we look at our `Calculator` class, a simple unittest via the build in `unittest` of Python looked something like: 17 | ```python 18 | import unittest 19 | from calculator import Calculator 20 | 21 | 22 | class TestCalculator(unittest.TestCase): 23 | def setUp(self): 24 | self.calculator = Calculator() 25 | 26 | def test_add(self): 27 | self.assertEqual(self.calculator.add(1, 2), 3) 28 | 29 | def test_subtract(self): 30 | self.assertEqual(self.calculator.subtract(5, 3), 2) 31 | 32 | if __name__ == '__main__': 33 | unittest.main() 34 | ``` 35 | 36 | Running the test would be done via: 37 | ``` 38 | python test_calculator.py 39 | ``` 40 | 41 | ### Converting to pytest 42 | If we want to use `pytest`, we need to install it via `pip` the package-manager of Python. 43 | ``` 44 | pip install pytest 45 | ``` 46 | 47 | We could now convert our unittest as follow 48 | ```python 49 | import pytest 50 | from calculator import Calculator # Assuming you have a Calculator class 51 | 52 | @pytest.fixture 53 | def calculator(): 54 | return Calculator() 55 | 56 | def test_add(calculator): 57 | assert calculator.add(1, 2) == 3 58 | 59 | def test_subtract(calculator): 60 | assert calculator.subtract(5, 3) == 2 61 | ``` 62 | 63 | We run this test by executing the following command: 64 | ``` 65 | pytest test_calculator.py 66 | ``` 67 | 68 |
69 | 70 | > Both pytest and unittest can be used and in the previous example you see no big difference, pytest uses `assert` for most testcases, which makes it easier to write. It also does not need a `if __name__ == "__main__"` that claass the test. 71 | 72 |
73 | 74 | ### Other languages 75 | While Pytest is popular in the Python community, other programming languages also have their own testing frameworks. For example: 76 | 77 | - NUnit/xUnit for .NET 78 | - JUnit for Java 79 | - Mocha for JavaScript 80 | - *many more...* 81 | 82 | Each of these frameworks has its unique features and conventions, but the underlying goal remains the same: to automate testing and catch issues early in the development process. 83 | 84 |
85 | 86 | ## Benefits 87 | Automating tests offers several advantages: 88 | 89 | **Efficiency**:
90 | Automated tests can be run quickly and repeatedly, saving time compared to manual testing. 91 | 92 | **Consistency**:
93 | Automated tests follow predefined steps consistently, reducing human error. 94 | 95 | **Regression Detection**:
96 | Automated tests catch regressions (unexpected issues introduced by code changes) early, preventing them from reaching production. 97 | 98 | **Continuous Integration (CI)**:
99 | Automated tests integrate seamlessly with CI/CD pipelines, ensuring that code changes don’t break existing functionality. 100 | 101 | **Documentation**:
102 | Test cases serve as living documentation, explaining how different parts of your application should behave. 103 | 104 | > In summary, automating tests improves code quality, accelerates development, and provides confidence in your software. 105 | 106 |
107 | 108 | > :memo: **Good to know**, in the next workshop will dive deeper into the subject of test automation via GitHub Actions. -------------------------------------------------------------------------------- /Workshop - Software Testing/05_tracking.md: -------------------------------------------------------------------------------- 1 | # Tracking with GitHub 2 | 3 | When it comes to bug tracking, GitHub provides an easy-to-implement yet powerful way to manage issues related to a code project. 4 | 5 |
6 | 7 | ## GitHub Issue Tracker 8 | GitHub has a built-in issue tracking system that allows you to log and manage issues directly within your repository. [More info about issue tracking](https://docs.github.com/en/issues/tracking-your-work-with-issues/planning-and-tracking-work-for-your-team-or-project) 9 | 10 | 1. **Creating Issues**: You can create new issues by navigating to the `Issues` tab in your repository. Click on the `New Issue` button, and provide details about the issue, including a title, description, and labels (such as “bug,” “enhancement,” etc.). 11 | 2. **Issue Details**: Each issue has a dedicated page where you can discuss the problem, provide additional context, and collaborate with other team members. You can also assign the issue to specific individuals. 12 | 3. **Labels and Milestones**: GitHub allows you to categorize issues using labels. For example, you can label an issue as “bug,” “feature request,” or “documentation.” Additionally, you can set milestones to track progress toward specific goals. 13 | 4. **Comments and Discussions**: Team members can comment on issues, discuss potential solutions, and provide updates. GitHub’s notification system ensures that relevant parties stay informed. 14 | 5. **Closing Issues**: Once an issue is resolved, you can close it. GitHub provides options to reference related pull requests, link to commits, and mark the issue as resolved. 15 | 16 |
17 | 18 | ## Branching 19 | 20 | Branches allow you to develop features, fix bugs, or safely experiment with new ideas in a contained area of your repository. When you create a branch, you’re essentially creating a separate copy of your codebase where you can work independently without affecting the main codebase. Each branch represents a specific task or feature. 21 | [More info about creating a branch in GitHub](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-a-branch-for-an-issue) 22 | 23 | ### Why branch? 24 | 1. **Isolation**: By creating a branch, you isolate your changes from the main codebase. This prevents accidental interference with other ongoing work. 25 | 2. **Collaboration**: Branches facilitate collaboration. Multiple team members can work on different branches simultaneously, and then merge their changes back into the main branch. 26 | 3. **Feature Development**: You can create feature branches to work on specific features or enhancements. Once the feature is complete, you merge it back into the main branch. 27 | 4. **Bug Fixes**: Branches are useful for fixing bugs. You create a branch, make the necessary fixes, and then merge it back. 28 | 5. **Experimentation**: If you want to try out a new idea without affecting the main code, create an experimental branch. 29 | 30 | ### Best practices 31 | Here are some best practies you could follow when creating branches.
32 | 33 | **Create from the Default Branch**
34 | Typically, you create a new branch from the default branch (often named “main” or “master”). This ensures your branch starts with the latest code. 35 | 36 | **Descriptive Names**
37 | Give your branches descriptive names (e.g., “feature/user-authentication” or “bugfix/404-page”). Clear names make it easier to understand the purpose of each branch. 38 | 39 | **Regularly Merge**
40 | Regularly merge changes from the default branch into your feature branch to keep it up-to-date. 41 | 42 | **Pull Requests**
43 | Use pull requests to propose merging your branch into the default branch. This allows for code review and discussion before merging. 44 | 45 | **Delete Stale Branches**
46 | After merging, delete branches that are no longer needed to keep your repository tidy 47 | 48 | > :bulb: **Remember** that every project is different, but it is always necessary to make good agreements about how you formulate things like Issues and Branches and how to deal with Bugs or new Features. [More info about flows](https://docs.github.com/en/get-started/using-github/github-flow) 49 | 50 |
51 | 52 | ## Classification 53 | 54 | Now, let’s discuss the defect life cycle and severity/priority classification: 55 | 56 | ### Defect Life Cycle: 57 | The defect life cycle encompasses various stages, including identification, logging, assignment, fixing, retesting, and closure. Each stage plays a crucial role in managing defects effectively. 58 | 59 | - **Identification**: Detecting defects during testing. 60 | - **Logging**: Creating detailed bug reports. 61 | - **Assignment**: Assigning the issue to the relevant team member. 62 | - **Fixing**: Developers address the issue. 63 | - **Retesting**: Verifying that the fix works. 64 | - **Closure**: Marking the defect as resolved. 65 | 66 | ### Severity and Priority Classification: 67 | #### Severity 68 | Refers to the impact of a defect on the system. It can be categorized as critical, major, minor, or trivial. 69 | - **Critical**: The defect causes system failure or data loss. 70 | - **Major**: Significant functionality is affected. 71 | - **Minor**: Minor functionality issues. 72 | - **Trivial**: Cosmetic issues with minimal impact. 73 | 74 | #### Priority 75 | Indicates the order in which defects should be addressed. Prioritization depends on business needs, user impact, and project timelines. 76 | - **High Priority**: Requires immediate attention. 77 | - **Medium Priority**: Important but not urgent. 78 | - **Low Priority**: Can be addressed later. -------------------------------------------------------------------------------- /Workshop - Software Testing/06_resources.md: -------------------------------------------------------------------------------- 1 | 2 | ### References and Further reading 3 | 4 | We throughly recommend these resources to continue your Testing practice: 5 | 6 | - Creating a branch for an issue 7 | - Planning and tracking work for your team or project 8 | - Follow GitHub flow to collaborate on projects 9 | - unittest - Unit testing framework 10 | - Unittesting via pytest in Python 11 | - Code Coverage via Coverage.py 12 | - Equivalence Partitioning 13 | - Boundary Value Analysis -------------------------------------------------------------------------------- /Workshop - UML/01_introduction.md: -------------------------------------------------------------------------------- 1 | # A need for diagrams 2 | In this workshop we give a brief overview of the Unified Modeling Language (UML), why it is useful and with a focus on its applications. But let's start with a story. 3 | 4 | ## The Voyager probe 5 | In the 1970s, NASA embarked on an ambitious mission to explore the outer planets of our solar system with the Voyager program. The twin spacecraft, Voyager 1 and Voyager 2, were designed to send back invaluable data about Jupiter, Saturn, Uranus, Neptune, and beyond. One of the critical aspects of the mission was ensuring reliable communication between the spacecraft and Earth across billions of miles. The engineers faced the challenge of designing a robust communication system that could handle the vast distances and extreme conditions of space. 6 | 7 | Meanwhile the probes have left our solar system. Due to this distance the communication bandwidth with the probes has dropped to only **120 bits per second** and it takes **22 hours** to reach the them. 8 | 9 |  10 | 11 | The Voyager probes send out regular 'pings' but one day the NASA engineers started to receive scrambled rubbish... After restarting the Computer Command System (CSS) it became clear that one of the memory banks was damaged by the high energy particles. Now image that you are tasked to reprogram the CSS. 12 | 13 | ### Activity 14 | What would be the first this you would do? 15 | 16 | #### Answer 17 | You would look for documentation describing the system. 18 | 19 | So you reach for the documentation and find the following diagram: 20 | 21 |  22 | 23 | Would this diagram be enough to apply your changes? 24 | 25 | #### Learning 1 26 | > Without knowing anything about the diagramming language used in the Block diagram, we were able to judge that it is not helpful for our purpose. So good diagram models are intuitive. 27 | 28 | ### Discussion time 29 | What documentation would we need? 30 | 31 | #### Possible answer 32 | Since we need to communicate with the Voyager probe, we need a communication protocol. 33 | 34 | It should describe: 35 | 36 | - What messages we can send 37 | - What the system does with our messages 38 | - Which response we get back 39 | 40 | #### Example 41 | When we lookup this protocol, we find the following description. 42 | 43 | **Communication Protocol** 44 | 45 | The communication takes place between two participants: 46 | 47 | 1. **Center Center** (referred to as "Center"): The communication control center. 48 | 2. **Voyager Probe** (referred to as "Voyager"): The Voyager space probe. 49 | 50 | The communication between **Center** and **Voyager** takes the following sequence: 51 | 52 | 1. The **Center** initiates a connection to the **Voyager** by sending a "Connect" message. 53 | 2. The **Voyager** receives the connection request and acknowledges it by sending an "Acknowledge Connection" message back to the **Center**. 54 | 3. The **Center** sends data to the **Voyager** with a "Send Data" message. 55 | 4. The **Voyager** processes the received data internally (represented by "Process Data"). 56 | 5. The **Voyager** acknowledges that the data has been received by sending an "Acknowledge Data Received" message to the **Center**. 57 | 6. The **Center** sends a "Disconnect" message to the **Voyager** to terminate the communication session. 58 | 7. The **Voyager** acknowledges the disconnection by sending an "Acknowledge Disconnection" message back to the **Center**. 59 | 60 | #### Activity 61 | What would this look like in a diagram? 62 | 63 | #### Compare results 64 | There are no wrong results here. Pick out some good ones and some unclear ones and discuss their clarity and expressiveness. The diagrams need to be useful. 65 | 66 | #### Possible solution 67 | The protocol could like something like: 68 | 69 |  70 | 71 | This protocol is based on the TCP protocol, but would this be handy for the Voyager communication? Why? For those interested, see the [TCP protocol](https://developer.mozilla.org/en-US/docs/Glossary/TCP) for more context. 72 | 73 | #### Learning 2 74 | > Diagrams are much easier to interpret than text. Expressing our documentation in diagrams therefore results in less interpretation errors (bugs) and faster implementation (development speed). 75 | 76 | ### Discussion time 77 | We now know how both participants communicate, but we don't yet know what they are saying. Or, in other words: what messages they pass around. 78 | 79 | - Do they have a header? 80 | - Do they have a built-in integrity check? 81 | 82 | #### Example 83 | The message might be structured like: 84 | 85 |  86 | 87 | #### Activity 88 | What does this diagram say? 89 | 90 | #### Possible solution 91 | The `opcode` describes the instruction for the CSS to execute and the `checksum` is added to check that the message has not corrupted during its 22 hour flight. The diagram says that the message consists of a header and a body. 92 | 93 | But this raises the question what the possible `opcode`s are. Hopefully this is documented as well... We will come back to this at the end of this workshop when we introduce Swagger documentation. This is documentation specifically designed for describing APIs. 94 | 95 | ## Conclusion 96 | Diagrams make our developer life easier than textual descriptions. -------------------------------------------------------------------------------- /Workshop - UML/04_swagger.md: -------------------------------------------------------------------------------- 1 | # API documentation 2 | In the introduction we were discussing how to describe the communication between NASA's Mission Control and the Voyager probes. We made a start with a Sequence diagram and a Class diagram to describe their communication, but it was not ideal. If we were to use UML for the Mission Control - Voyager interface then it would result in a lot of diagrams without a clear overview. That's why tools like Swagger were invented. 3 | 4 | ## What is Swagger? 5 | Swagger is a way to document your REST API in a **standardized** way. The best way to explore what Swagger really is, is to view Swagger's Petstore example: 6 | 7 | [Swagger Petstore API](https://petstore.swagger.io) 8 | 9 | ## Things to explore 10 | 11 | ### The general description 12 | On top we find a title and a description. You have some freedom here and it is up to you to give a clear description of your API. 13 | 14 | ### Endpoints 15 | Swagger allows you to organize CRUD actions per endpoint. Here we see GET, POST, PUT and DELETE actions for the endpoints **pet**, **store** and **user**. 16 | 17 | ### Requests 18 | The request part describes the request and its response in details. Expanding the pet's PUT we find: 19 | 20 | - The body and that this field is required 21 | - The model that we must send and an example 22 | - When you run `execute` we see the response 23 | 24 | ### Models 25 | The model descriptions are extracted from the endpoint models. 26 | 27 | Anything that is relevant for developers is present in the documentation. Now it's time to build your own Swagger doc. 28 | 29 | ### Activity 30 | Suppose your company needs to build a basic calculator. It should handle: 31 | 32 | - Additions 33 | - Subtractions 34 | - Multiplications 35 | - Divisions 36 | 37 | One of the requirements is that the calculator must be available for mobile, desktop and web. Your company decides not to build the mobile, desktop and web client itself; they leave that to other vendors. But they do provide the calculator API. The code base is provided to you, see `app.py`. 38 | 39 | It's your task to let the other developers know how to use the API: 40 | 41 | - Describe the API with Swagger 42 | - You can use the json or yaml variant for this 43 | - Use the [Swagger specification](https://swagger.io/specification) in combination with [Swagger Petstore](https://petstore.swagger.io) example 44 | 45 | Present your documentation by loading your json/yaml file into [Swagger's online Editor](https://editor.swagger.io). 46 | 47 | Like the Petstore example, Swagger documentation can be made interactive but that is beyond the scope of this workshop. See the resources for a tutorial. -------------------------------------------------------------------------------- /Workshop - UML/05_resources.md: -------------------------------------------------------------------------------- 1 | 2 | ## Voyager Program 3 | - [Voyager program](https://en.wikipedia.org/wiki/Voyager_program) 4 | - [Tachtigers houden Voyager in de vaart](https://www.bnr.nl/podcast/de-technoloog/10549902/tachtigers-houden-voyager-in-de-vaart) 5 | - [The untold truth of the Voyager Program](https://www.grunge.com/949833/the-untold-truth-of-the-voyager-program/) 6 | - [The Brains of the Voyager Spacecraft](https://www.allaboutcircuits.com/news/voyager-mission-anniversary-computers-command-data-attitude-control/) 7 | 8 | ## UML 9 | - [UML Wikipedia](https://en.wikipedia.org/wiki/Unified_Modeling_Language) 10 | - [Geeks For Geeks](https://www.geeksforgeeks.org/structural-diagrams-unified-modeling-languageuml) 11 | - [UML spec](https://www.omg.org/spec/UML) 12 | 13 | ## Diagrams 14 | - [Use Case Diagram](https://www.geeksforgeeks.org/use-case-diagram) 15 | - [Activity Diagram](https://www.geeksforgeeks.org/unified-modeling-language-uml-activity-diagrams) 16 | - [Class Diagram](https://www.geeksforgeeks.org/unified-modeling-language-uml-class-diagrams) 17 | - [Sequence Diagram](https://www.geeksforgeeks.org/unified-modeling-language-uml-sequence-diagrams) 18 | - [State Diagram](https://www.geeksforgeeks.org/unified-modeling-language-uml-state-diagrams) 19 | - [Deployment Diagram](https://www.geeksforgeeks.org/deployment-diagram-unified-modeling-languageuml) 20 | - [Deployment Diagram](https://www.youtube.com/watch?v=IzEzX5HW_CU) 21 | 22 | ## PlantUML 23 | - [PlantUML Site](https://plantuml.com) 24 | - [PlantUML VSCode Plugin](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml) 25 | - [Configuring and Running PlantUML with VS Code](https://medium.com/@sadaf.cuagain/configuring-and-running-plantuml-with-vs-code-8f2f6e64bb8d) 26 | - [PlantUML Github Actions](https://github.com/marketplace/actions/generate-plantuml) 27 | 28 | ## UML Critique 29 | - [Are UML Diagrams Important for Developers?](https://www.youtube.com/watch?v=VZgsxw0Og6c) 30 | 31 | ## Swagger 32 | - [Swagger Site](https://swagger.io) 33 | - [Swagger Open Source Tools](https://swagger.io/tools/open-source) 34 | - [OpenAPI Specification](https://swagger.io/specification) 35 | - [Swagger Parser](https://apitools.dev/swagger-parser) 36 | - [Swagger Tutorial](https://www.youtube.com/watch?v=xQfMARPNycI) 37 | 38 | ## Other 39 | - [Mermaid tool](https://mermaid.js.org/) 40 | -------------------------------------------------------------------------------- /Workshop - UML/draw_io/voyager_1.drawio: -------------------------------------------------------------------------------- 1 |
5 | 6 | ## General 7 | You will work as a developer in a small team (max 4 students), where you will work together on existing (legacy) software in Python based on the available case. 8 | During this course, you will have to analyze, map, test and then refactor the software. At the same time, you will set up a CI/CD pipeline to continue testing, logging and monitoring during the development process. 9 | If everything goes well, you will expand the application with extra functionality. 10 | 11 |
12 | 13 | ## Workshops 14 | 15 | ### Workshop 1 - REST + Requirements Specifications 16 | In this workshop we will look at how to draw up requirements. 17 | What are good requirements and what should they meet, among other things. 18 | What is REST and how do APIs work, a short introduction and how to draw up requirements for it. 19 | Using examples, you will look at how you could analyze requirements from existing software, among other things. 20 | 21 | ### Workshop 2 – Git 22 | In this workshop we will look at the use of Git and GitHub. What terms are used and 23 | what are they for, what is the normal way of working with Git and what is the difference with GitHub. 24 | Throughout the course Git is the lifeblood of CI/CD and now we look at what, why and 25 | how you use it. 26 | 27 | ### Workshop 3 - Software Testing 28 | In this workshop we will look at testing software. 29 | What do you test when, what methods are there to test and what do you need to take into account. 30 | What tools can you use and how will this help within our CI/CD pipeline. 31 | 32 | ### Workshop 4 – Refactoring 33 | In this workshop we will look at refactoring, what is it, what do you use it for and how do you apply it? 34 | How does refactoring contribute to making your software more maintainable and how can we apply this to an existing project? 35 | 36 | ### Workshop 5 - CI/CD 37 | In this workshop we will look at Continuous Integration (CI) and Continuous Development (CD), 38 | what is it, what do we use it for and what is the difference between Continuous Development and Continuous Delivery. 39 | We will look at tools, settings and start with the setup. 40 | 41 | ### Workshop 6 - Operating Systems + Bash 42 | In this workshop we will look at the use of Bash and its power within CI/CD. 43 | How different Operating Systems differ from each other. 44 | How to navigate between folders, how to create files, how to move and delete files and how to set permissions. 45 | 46 | ### Workshop 7 – UML 47 | In this workshop we will delve deeper into the use and power of UML as a language for visually representing software or changes in software. 48 | We will look at the following components: Context diagram, ERD, Deployment diagram, Flowchart, State diagram, Swagger/OpenAPI --------------------------------------------------------------------------------