diff --git a/0-git-setup-slides.html b/0-git-setup-slides.html new file mode 100644 index 0000000..22f9d27 --- /dev/null +++ b/0-git-setup-slides.html @@ -0,0 +1,205 @@ +Project management 0. Git setup
+

Project management 0. Git setup

+
+
+

Contents

+ +
+
+

What is Git?

+
    +
  • Git is a version control tool originally created by Linus Torvalds in 2005
    • +
  • Keeps track of code changes
    • +
  • Can be used to backup code in the cloud
    • +
  • Enables cooperation with other team members
    • +
  • Ubiquitous in software development
    • +
+
+
+

Git vs cloud storage

+
    +
  • Git is different from cloud storage services like Dropbox, Google Drive or OneDrive +
      +
    • Instead of automatic syncing, you deliberately push to and pull from the cloud
      • +
    • Cloud services are easier for starters
      • +
    • ...but in projects of more than one person, tracking changes would be a pain
      • +
    +
    • +
  • Git has a steep learning curve +
      +
    • To ease things, there are some visual tools like Sourcetree or Sublime Merge
      • +
    • To use them effectively, you still need to understand how Git works, though
      • +
    +
    • +
+
+
+

GitHub and other developer platforms

+
    +
  • Git could be used locally, but its usage is almost always combined with a developer platform — a remote storage service like GitHub, GitLab or BitBucket +
      +
    • These services can also double as a programming portfolio
      • +
    • Commonly used in both open source and commercial projects
      • +
    +
    • +
  • In Buutti's trainings, GitLab is most commonly used
    • +
+
+
+

Setup

+
    +
  • Install Git +
      +
    • Windows/Mac: git-scm.com +
        +
      • Installation instructions are included in the following slides.
        • +
      • If a setting is not mentioned in the instructions, you can leave it as the default option.
        • +
      +
      • +
    • Linux: sudo apt-get install git
      • +
    +
    • +
+
+
+

Git setup: Settings for Windows

+
+
+

+
+
+

+

Set manually after setup with:

+
git config --global core.editor "code --wait"
+
+
+
+
+
+
+
+

+

Set manually after setup with:

+
git config --global init.defaultBranch main
+
+
+
+

+
+
+
+
+
+
+

+
+
+

+
+
+
+
+
+
+

+

Set manually after setup with:

+
git config --global credential.helper wincred
+
+
+
+

+
+
+
+
+

Command line

+
    +
  • Git is operated via the command line, a.k.a, the terminal
    • +
  • There are many kinds of command line syntaxes out there. Some examples: +
      +
    • Windows: PowerShell (new), cmd (old)
      • +
    • Linux, (also included in the Windows Git install): bash
      • +
    +
    • +
  • We're using PowerShell, which can be accessed inside VS Code
    • +
  • In VS Code, open/close terminal by pressing CTRL+Ö (in the Fin/Swe layout)
    • +
+
+
+

Basic commands and the working directory

+
    +
  • To do actions in Git, you don't press buttons, you write commands
    • +
  • Most commands act on the currently open folder, a.k.a. the working directory +
      +
    • Path to the directory is shown next to the terminal cursor:
      +PS E:\borb\code\unity-basics-course>
      • +
    +
    • +
  • ls tells the contents of the working directory
    • +
  • cd is used to move to another directory +
      +
    • Use cd programming to move to the programming subfolder
      +PS E:\borb\code\unity-basics-course\programming>
      • +
    • Use cd .. to move one step up in the hierarchy (to the parent directory)
      +PS E:\borb\code\unity-basics-course>
      • +
    +
    • +
  • Note: .. is a shorthand for to the parent directory, . for the current directory
    • +
+
+
+

Extra: Help, this is horrible!

+ +
    +
  • Do you feel more at home in graphical UIs? +
      +
    • There are also graphical user interfaces for Git like GitKraken, Sublime Merge or GitHub Desktop (GitHub only)
      • +
    • VS Code also has very useful graphical tools for Git (more about them later!)
      • +
    +
    • +
  • However, the GUIs make a lot more sense after you've understood the Git commands that those GUIs still execute under the hood +
      +
    • There is no free lunch here
      • +
    +
    • +
+
+
+

Btw: Config

+
    +
  • To configure your Git username for every project: +
      +
    • Use git config --global user.name "myUserName"
      • +
    • and git config --global user.email "my.email.address@domain.com"
      • +
    +
    • +
  • If you do not do this, Git will ask to do it anyway at some point
    • +
+
+
\ No newline at end of file diff --git a/0-git-setup.md b/0-git-setup.md new file mode 100644 index 0000000..61bc2df --- /dev/null +++ b/0-git-setup.md @@ -0,0 +1,171 @@ +--- +title: Project management 0. Git setup +marp: true +paginate: true +theme: buutti +--- + + + +# Project management 0. Git setup + +## Contents + +- [Contents](#contents) +- [What is Git?](#what-is-git) +- [GitHub and other developer platforms](#github-and-other-developer-platforms) +- [Setup](#setup) +- [Git setup: Settings for Windows](#git-setup-settings-for-windows) +- [Command line](#command-line) +- [Extra: Help, this is horrible!](#extra-help-this-is-horrible) +- [Btw: Config](#btw-config) + + + +## What is Git? + +* Git is a version control tool originally created by Linus Torvalds in 2005 +* Keeps track of code changes +* Can be used to backup code in the cloud +* Enables cooperation with other team members +* Ubiquitous in software development + +### Git vs cloud storage + +* Git is different from cloud storage services like Dropbox, Google Drive or OneDrive + * Instead of automatic syncing, you deliberately *push to* and *pull from* the cloud + * Cloud services are easier for starters + * ...but in projects of more than one person, tracking changes would be a pain +* Git has a steep learning curve + * To ease things, there are some visual tools like **Sourcetree** or **Sublime Merge** + * To use them effectively, you still need to understand how Git works, though + +## GitHub and other developer platforms + +* Git *could* be used locally, but its usage is almost always combined with a developer platform — a remote storage service like [GitHub](https://github.com/), [GitLab](https://gitlab.com/) or [BitBucket](https://bitbucket.com/) + * These services can also double as a programming portfolio + * Commonly used in both open source and commercial projects +* In Buutti's trainings, GitLab is most commonly used + +## Setup + +* Install Git + * Windows/Mac: [git-scm.com](https://git-scm.com) + * Installation instructions are included in the following slides. + * If a setting is not mentioned in the instructions, you can leave it as the default option. + * Linux: `sudo apt-get install git` + +## Git setup: Settings for Windows + +
+
+ +![](imgs/git1.png) + +
+
+ +![](imgs/git3.png) + +Set manually after setup with: +``` +git config --global core.editor "code --wait" +``` + +
+
+ +--- + +
+
+ +![](imgs/git2.png) + +Set manually after setup with: + ``` + git config --global init.defaultBranch main + ``` + +
+
+ +![](imgs/git4.png) + +
+
+ +--- + +
+
+ +![](imgs/git5.png) + +
+
+ +![](imgs/git6.png) + +
+
+ +--- + +
+
+ +![](imgs/git7.png) + +Set manually after setup with: + +``` +git config --global credential.helper wincred +``` + +
+
+ +![](imgs/git8.png) + +
+
+ +## Command line + +* Git is operated via the ***command line***, a.k.a, the ***terminal*** +* There are many kinds of command line syntaxes out there. Some examples: + * Windows: ***PowerShell*** (new), ***cmd*** (old) + * Linux, (also included in the Windows Git install): ***bash*** +* We're using PowerShell, which can be accessed inside VS Code +* In VS Code, open/close terminal by pressing ***CTRL+Ö*** (in the Fin/Swe layout) + +### Basic commands and the working directory + +* To do actions in Git, you don't press buttons, you write commands +* Most commands act on the currently open folder, a.k.a. the ***working directory*** + * ***Path*** to the directory is shown next to the terminal cursor: + `PS E:\borb\code\unity-basics-course>` +* `ls` tells the contents of the working directory +* `cd` is used to move to another directory + * Use `cd programming` to move to the `programming` subfolder + `PS E:\borb\code\unity-basics-course\programming>` + * Use `cd ..` to move one step up in the hierarchy (to the parent directory) + `PS E:\borb\code\unity-basics-course>` +* ***Note***: `..` is a shorthand for to the parent directory, `.` for the current directory + +## Extra: Help, this is horrible! + + +* Do you feel more at home in graphical UIs? + * There are also graphical user interfaces for Git like [GitKraken](https://www.gitkraken.com/), [Sublime Merge](https://www.sublimemerge.com/) or [GitHub Desktop](https://desktop.github.com/) (GitHub only) + * VS Code also has very useful graphical tools for Git (more about them later!) +* However, the GUIs make ***a lot*** more sense after you've understood the Git commands that those GUIs still execute under the hood + * There is no free lunch here + +## Btw: Config + +* To configure your Git username for every project: + * Use `git config --global user.name "myUserName"` + * and `git config --global user.email "my.email.address@domain.com"` +* If you do not do this, Git will ask to do it anyway at some point \ No newline at end of file diff --git a/1-git-basics-slides.html b/1-git-basics-slides.html new file mode 100644 index 0000000..8174301 --- /dev/null +++ b/1-git-basics-slides.html @@ -0,0 +1,343 @@ +Project management 1. Git basics
+

Project management 1. Git basics

+
+
+

Basic Git workflow

+
    +
  • You have to tell everything you want to happen to Git explicitly by using Git commands
    • +
  • A common Git workflow consists of these four steps:
    • +
+
    +
  1. Edit: You make changes in some code file
    2. +
  2. Stage: You tell Git what files you've changed (git add)
    3. +
  3. Commit: You tell Git what changes you made in that file (git commit)
    4. +
  4. Push: You upload those changes to a remote repository (git push)
    5. +
+
+
+

Repositories

+
    +
  • Repository is essentially a place to store code files in
    • +
  • Usually, we are dealing with two repositories: a local and a remote one +
      +
    • A local repository is the one on your computer
      • +
    • A remote repository is stored in a cloud service like GitHub
      • +
    • Here is the remote repository for the materials of this course
      • +
    • Changes are synced between these two repositories manually
      • +
    +
    • +
+
+
+

git init

+
    +
  • Initialization needs to be done for every new Git repository
    • +
  • There are two ways to initialize a repo: +
      +
    • a) Creating the local repository first: +
        +
      • Use git init to make your current folder a new Git repository
        • +
      +
      • +
    • b) Creating the remote repository first / continuing an existing project: +
        +
      • Clone a remote repository into your computer (See: git clone)
        • +
      +
      • +
    +
    • +
  • Note: Never initialize a Git repository in a cloud storage folder!
    • +
+
+
+

.git folder

+
    +
  • Initialization adds a hidden .git folder inside a directory +
      +
    • This is where Git stores all its repository data.
      • +
    • Do not touch it!
      • +
    +
    • +
  • The .git folder ONLY appears in the root directory of the repository +
      +
    • If you see the .git folder in any of the subdirectories of the repository, something has gone wrong!
      • +
    • You have initialized a repository inside repository
      • +
    +
    • +
+
+
width:
+

git status

+
    +
  • Using the command git status shows your current situation.
    • +
  • If you're unsure what to do, it's never a bad idea to run git status
    • +
+
+
+

git add

+
    +
  • Uploading changes to GitHub from your local machine takes three steps (see Basic Git workflow from earlier)
    • +
  • The first phase is staging with git add: +
      +
    • The command git add readme.md stages the file readme.md
      • +
    • After doing it, git status tells this:
      Changes to be committed:
+  (use "git restore --staged <file>..." to unstage)
+        modified:   readme.md
+
      +
      • +
    +
    • +
+
+
+
    +
  • Basically, with git add file you tell Git that you want to do something with file.
    • +
  • Note: If you just want to push all the changes you've made, you can use git add . to stage all the files in your current folder and its subfolders +
      +
    • Be careful! Only do this after checking what changes have been made with git status
      • +
    +
    • +
  • Note 2: Use git add <filename> -p if you only want to stage some lines from a file you've worked on.
    • +
  • Note 3: The counterpart to git add is git rm, which removes previously added files from Git's perspective
    • +
+
+
+

git commit

+
    +
  • After you have staged all the files you want, the second step is to commit your changes +
      +
    • In the commit, you will explain what changes you've made
      • +
    • This message will be visible in GitHub
      • +
    • git commit -m "add new enemy"
      • +
    +
    • +
  • Every new commit creates a new point in the project timeline. +
      +
    • You can always jump back between different points (See git checkout)
      • +
    +
    • +
  • Commit message should clearly, concisely tell what kind of changes you have made
    • +
+
+
+

git push

+
    +
  • The third step is pushing the changes to GitHub
    • +
  • The previously-made commit action is local +
      +
    • No changes have gone to the remote repository yet!
      • +
    • To upload changes to the remote repository, use git push
      • +
    • Then you're done!
      • +
    +
    • +
+
+
+
    +
  • Note: When pushing for the first time, Git might nag you:
    fatal: The current branch master has no upstream branch.
+To push the current branch and set the remote as upstream, use
+
+    git push --set-upstream origin main
+
    +
    • +
  • You can just follow its orders (see the command on the third line!) and you're good to go
    • +
  • Generally, when Git gives you a warning, error, or some other message, it's a good idea to read it and follow the orders.
    • +
+
+
+

git remote

+
    +
  • If you have initialized a Git repo already with git init, don't use git clone! +
      +
    • Instead, run git remote add origin <URL>
      • +
    • Here, the name origin refers to the remote repository
      • +
    • origin is just the default name for a remote: other names can be used instead!
      • +
    +
    • +
  • To check which remote repository the current local repository is linked to, use +
      +
    • git remote -v
      • +
    +
    • +
+
A repository can have multiple remotes. Use git remote to list them all.
+
+
+

Exercise 1a. Initializing a repo

+ +
    +
  • Initialize a new repository locally.
    • +
  • Create a new file GitTest.md with some lines of text in it.
    • +
  • Commit changes.
    • +
  • Create a new empty repository on GitHub.
    • +
  • Use git remote add origin <url> to connect your local repo to the GitHub repo.
    • +
  • Push changes to GitHub. Go to GitHub and see that GitTest.md is there!
    • +
+
+
+

git pull

+
    +
  • git pull applies changes from the remote repository into the local repository +
      +
    • Counterpart to push
      • +
    +
    • +
  • Very common when working in a team +
      +
    • Note: During teamwork it's a good idea to always pull before pushing
      • +
    +
    • +
  • If you only work alone on a single computer, seldom needed
    • +
+
git pull is actually two commands in one. It's the same thing as doing git fetch <branch> + git merge <branch>
+
+
+

git clone

+
    +
  • Remote repositories have an URL address that can be used to download the code to your machine +
      +
    • The address can be found under the Clone button in the repository webpage
      • +
    +
    • +
  • Use the URL to download a remote repository: +
      +
    • Run git clone <URL>
      • +
    • Example: git clone https://github.com/borbware/unity-basics-course.git
      • +
    • Remember: this initializes the repo, so git init not needed.
      • +
    +
    • +
  • Simplest way to create a new, empty repository: +
      +
    • 1 - Initialize the repo in the Github/Gitlab/etc website
      • +
    • 2 - Clone the repo.
      • +
    +
    • +
+
+
+

Exercise 1b. Cloning a repo

+ +
    +
  • Create a new repository on GitHub and clone it with HTTPS to your machine.
    • +
  • Then, create a new file GitTest.md with some lines of text in it.
    • +
  • Commit and push changes to GitHub.
    • +
  • Go to GitHub and see that the file is there!
    • +
+
+
+

Extra: HTTPS vs SSH

+ +
    +
  • There are two ways to communicate with GitHub, HTTPS and SSH
    • +
  • HTTPS: https://github.com/borbware/unity-basics-course.git +
      +
    • the easier way
      • +
    • you log in with your GitHub credentials that get stored in the Git Credential Manager
      • +
    +
    • +
  • SSH: git@github.com:borbware/unity-basics-course.git + +
    • +
+
+
+

.gitignore

+
    +
  • Sometimes your project has local files that should NOT be uploaded to GitHub +
      +
    • List those files in a .gitignore file in your Git project folder
      • +
    +
    • +
  • You can create it by yourself and define file names or folders which Git will then ignore in the commits, e.g.,
      someScript.cs
+  /folder
+  *.html
+
    +
    • +
  • Note: If you add a file to .gitignore that was committed earlier, Git doesn't "forget" it automatically. +
      +
    • You can make Git forget it with git rm --cached filename
      • +
    +
    • +
+
+
width:
+

VS code: Source control

+
    +
  • The source control tab is very useful for managing your Git workflow
    • +
  • Unstaged changes are shown under Changes +
      +
    • Press "" to stage a file
      • +
    +
    • +
  • Staged files are shown under Staged changes +
      +
    • Press "" to unstage a file
      • +
    • Press " 📄" to open the file
      • +
    +
    • +
  • Click the filename to see what changes you've made in a side-by-side comparison view (see the next slide!)
    • +
  • Press "" to discard the changes made to the file (be careful!)
    • +
+
+
+
+

Exercise 2. Git collaboration

+ +
    +
  • Work on this exercise with your group.
    • +
  • Choose someone's test repository from Exercise 1b to use in this exercise.
    • +
  • While others clone the repo to their machine, the owner should add other group members as collaborators of the repo in the repository's settings on GitHub.
    • +
  • Then, everyone should make changes to the markdown file in the repository!
    • +
+

What happens if you make changes to the same line simultaneously?

+
In GitLab, the setting is under Manage > Members
+
+
+

Troubleshooting: master vs. main

+
error: failed to push some refs to [your-url]
+
+
    +
  • Possible reason: GitHub has a main branch, while your local repository has master
    • +
  • Fix: Run git branch -m main to rename your local master to main
    • +
+
+
+

Note about longer push and pull commands

+
    +
  • After initialization, why do I have to use longer push and pull commands? +
      +
    • Short answer: because we didn't clone the repo, but rather added the remote into an empty one with git remote add origin.
      • +
    • git pull origin main: After adding a remote, we don't yet know which branch to pull from. main (or master!) is the default branch
      • +
    • git push --set-upstream origin main: In the first push, we decide which branch to link our current branch into.
      • +
    • Afterwards, we can just use git push and git pull.
      • +
    +
    • +
+
+
+

Reading

+ +
+
\ No newline at end of file diff --git a/1-git-basics.md b/1-git-basics.md new file mode 100644 index 0000000..9d3336b --- /dev/null +++ b/1-git-basics.md @@ -0,0 +1,229 @@ +--- +title: Project management 1. Git basics +marp: true +paginate: true +math: mathjax +theme: buutti +--- + + + +# Project management 1. Git basics + +## Basic Git workflow + +* You have to tell everything you want to happen to Git ***explicitly*** by using ***Git commands*** +* A common Git workflow consists of these four steps: + 1) ***Edit:*** You make changes in some code file + 2) ***Stage:*** You tell Git what files you've changed ([`git add`](#git-add)) + 3) ***Commit:*** You tell Git what changes you made in that file ([`git commit`](#git-commit)) + 4) ***Push:*** You upload those changes to a remote repository ([`git push`](#git-push)) + +## Repositories + +* ***Repository*** is essentially a place to store code files in +* Usually, we are dealing with ***two*** repositories: a ***local*** and a ***remote*** one + * A local repository is the one on your computer + * A remote repository is stored in a cloud service like GitHub + * [Here](https://github.com/borbware/unity-basics-course) is the remote repository for the materials of this course + * Changes are synced between these two repositories ***manually*** + +## `git init` + +* Initialization needs to be done for every new Git repository +* There are two ways to initialize a repo: + * a) Creating the local repository first: + * Use `git init` to make your current folder a new Git repository + * b) Creating the remote repository first **/** continuing an existing project: + * *Clone* a remote repository into your computer (See: [`git clone`](#git-clone)) +* ***Note:*** Never initialize a Git repository in a cloud storage folder! + +## `.git` folder + +* Initialization adds a hidden `.git` folder inside a directory + * This is where Git stores all its repository data. + * ***Do not touch it!*** +* The .git folder ONLY appears in the root directory of the repository + * If you see the `.git` folder in any of the subdirectories of the repository, something has gone wrong! + * You have initialized a repository inside repository + +## `git status` + +* Using the command `git status` shows your current situation. +* If you're unsure what to do, it's never a bad idea to run `git status` + +![bg right width: 80%](imgs/git-status.png) + +## `git add` + +* Uploading changes to GitHub from your local machine takes three steps (see [Basic Git workflow](1-git-basics#basic-git-workflow) from earlier) +* The first phase is ***staging*** with `git add`: + * The command `git add readme.md` stages the file `readme.md` + * After doing it, `git status` tells this: + ``` + Changes to be committed: + (use "git restore --staged ..." to unstage) + modified: readme.md + ``` + +--- + +* Basically, with `git add file` you tell Git that you want to do *something* with `file`. +* ***Note:*** If you just want to push all the changes you've made, you can use `git add .` to stage all the files in your current folder and its subfolders + * Be careful! Only do this after checking what changes have been made with `git status` +* ***Note 2:*** Use `git add -p` if you only want to stage **some** lines from a file you've worked on. +* ***Note 3:*** The counterpart to `git add` is `git rm`, which removes previously added files from Git's perspective + +## `git commit` + +* After you have staged all the files you want, the second step is to ***commit*** your changes + * In the commit, you will explain what changes you've made + * This message will be visible in GitHub + * `git commit -m "add new enemy"` +* Every new commit creates a new point in the project timeline. + * You can always jump back between different points (See `git checkout`) +* Commit message should clearly, concisely tell what kind of changes you have made + +## `git push` + +* The third step is ***pushing*** the changes to GitHub +* The previously-made commit action is **local** + * No changes have gone to the remote repository yet! + * To upload changes to the remote repository, use `git push` + * Then you're done! +--- +* ***Note:*** When pushing for the first time, Git might nag you: + ``` + fatal: The current branch master has no upstream branch. + To push the current branch and set the remote as upstream, use + + git push --set-upstream origin main + ``` +* You can just follow its orders (see the command on the third line!) and you're good to go +* Generally, when Git gives you a warning, error, or some other message, it's a good idea to ***read it and follow the orders***. + +## `git remote` + +* If you have initialized a Git repo already with `git init`, don't use `git clone`! + * Instead, run `git remote add origin ` + * Here, the name `origin` refers to the remote repository + * `origin` is just the default name for a remote: other names can be used instead! +* To check which remote repository the current local repository is linked to, use + * `git remote -v` + + + +## Exercise 1a. Initializing a repo + + +* Initialize a new repository locally. +* Create a new file `GitTest.md` with some lines of text in it. +* Commit changes. +* Create a new empty repository on GitHub. +* Use `git remote add origin ` to connect your local repo to the GitHub repo. +* Push changes to GitHub. Go to GitHub and see that `GitTest.md` is there! + +## `git pull` + +* `git pull` applies changes from the remote repository into the local repository + * Counterpart to `push` +* Very common when working in a team + * **Note**: During teamwork it's a good idea to ***always pull before pushing*** +* If you only work alone on a single computer, seldom needed + + + +## `git clone` + +* Remote repositories have an URL address that can be used to download the code to your machine + * The address can be found under the *Clone* button in the repository webpage +* Use the URL to download a remote repository: + * Run `git clone ` + * Example: `git clone https://github.com/borbware/unity-basics-course.git` + * Remember: this initializes the repo, so `git init` not needed. +* Simplest way to create a new, empty repository: + * 1 - Initialize the repo in the Github/Gitlab/etc website + * 2 - Clone the repo. + + +## Exercise 1b. Cloning a repo + + +* Create a new repository on GitHub and clone it with HTTPS to your machine. +* Then, create a new file `GitTest.md` with some lines of text in it. +* Commit and push changes to GitHub. +* Go to GitHub and see that the file is there! + +## Extra: HTTPS vs SSH + + +* There are two ways to communicate with GitHub, ***HTTPS*** and ***SSH*** +* HTTPS: `https://github.com/borbware/unity-basics-course.git` + * the easier way + * you log in with your GitHub credentials that get stored in the Git Credential Manager +* SSH: `git@github.com:borbware/unity-basics-course.git` + * [Connecting to GitHub with SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) + * You need to generate a computer-specific SSH key and add it to your GitHub settings + +## `.gitignore` + +* Sometimes your project has local files that should ***NOT*** be uploaded to GitHub + * List those files in a `.gitignore` file in your Git project folder +* You can create it by yourself and define file names or folders which Git will then ignore in the commits, e.g., + ``` + someScript.cs + /folder + *.html + ``` +* ***Note:*** If you add a file to `.gitignore` that was committed earlier, Git doesn't "forget" it automatically. + * You can make Git forget it with `git rm --cached filename` + +## VS code: Source control + +* The ***source control*** tab is very useful for managing your Git workflow +* Unstaged changes are shown under ***Changes*** + * Press "$+$" to stage a file +* Staged files are shown under ***Staged changes*** + * Press "$-$" to unstage a file + * Press "$\curvearrowright$ 📄" to open the file +* Click the filename to see what changes you've made in a side-by-side comparison view (see the next slide!) +* Press "$\curvearrowleft$" to discard the changes made to the file (be careful!) + +![bg left:33% width: 80%](imgs/vscode-source-control.png) + +--- + +![bg height:90%](imgs/vscode-working-tree.png) + +## Exercise 2. Git collaboration + + +* Work on this exercise with your group. +* Choose someone's test repository from Exercise 1b to use in this exercise. +* While others clone the repo to their machine, the owner should add other group members as collaborators of the repo in the repository's settings on GitHub. +* Then, everyone should make changes to the markdown file in the repository! + +What happens if you make changes to the same line simultaneously? + + + +## Troubleshooting: master vs. main + +``` +error: failed to push some refs to [your-url] +``` + +* Possible reason: GitHub has a `main` branch, while your local repository has `master` +* ***Fix:*** Run `git branch -m main` to rename your local `master` to `main` + +## Note about longer `push` and `pull` commands + +* After initialization, why do I have to use longer `push` and `pull` commands? + * Short answer: because we didn't clone the repo, but rather added the remote into an empty one with `git remote add origin`. + * `git pull origin main`: After adding a remote, we don't yet know which ***branch*** to pull from. `main` (or `master`!) is the default branch + * `git push --set-upstream origin main`: In the first `push`, we decide which branch to link our current branch into. + * Afterwards, we can just use `git push` and `git pull`. + +## Reading + +* [Using version control in VS code](https://code.visualstudio.com/docs/sourcecontrol/overview) \ No newline at end of file diff --git a/2-git-continued-slides.html b/2-git-continued-slides.html new file mode 100644 index 0000000..0d56959 --- /dev/null +++ b/2-git-continued-slides.html @@ -0,0 +1,395 @@ +Project management 2. Git continued
+

Project management 2. Git continued

+
+
width:
+

Branches

+
    +
  • A Git repository can have multiple branches
    • +
  • By default, a Git repository has only one branch +
      +
    • named either master or main
      • +
    +
    • +
  • Using multiple branches makes it possible to work on new features step by step in their own feature branches +
      +
    • Meanwhile, the master branch is kept clean and in a working state
      • +
    • Only when the feature is completed, the branch is merged into the master branch!
      • +
    +
    • +
+
+
+

Active branch

+
    +
  • Even though your local repository can have multiple branches, only one of them is active at a given time
    • +
  • git status tells you firsthand which branch you are on: On branch master
    • +
+
+
+

git branch & git checkout

+
    +
  • You can create a new branch with git branch <branchName> +
      +
    • The new branch is not empty: it contains a copy of the code of the branch you executed this command in
      • +
    +
    • +
  • Note: git branch <branchName> does not make the branch active!
    • +
  • To make the branch active, a.k.a "move" to the branch: +
      +
    • git checkout <branchName>.
      • +
    • For example, to move back to master use git checkout master
      • +
    +
    • +
+
+
+

Local vs. remote branches

+
    +
  • git branch <branchName> only creates a local branch
    • +
  • When you try to push changes from a new local branch, Git nags you that a matching remote branch doesn't yet exist +
      +
    • Git tells you how to create the remote branch: +
        +
      • git push --set-upstream origin <newBranch>
        • +
      • Afterwards, git push pushes the changes to the matching remote branch
        • +
      +
      • +
    +
    • +
+
+
+

Extra branch commands

+
    +
  • Handy command: git checkout -b <branchName> +
      +
    • It's a shorthand for git branch <branchName> + git checkout <branchName>
      • +
    +
    • +
  • Get a list of local branches with git branch +
      +
    • ...and all branches (incl. the remote ones) with git branch -a
      • +
    +
    • +
  • Delete a local branch with git branch -d <branchName> +
      +
    • Remote branch can be deleted in the GitHub/etc website
      • +
    • ...or with git push origin -d <branchName>
      • +
    • Note: If deleted remote branches still show up in git branch -a, you can use the command git remote prune origin to remove them from the list.
      • +
    +
    • +
+
+
+

git merge

+
    +
  • So you've been working on a feature branch. What next?
    • +
  • When the feature is done (and all the broken things fixed), you want to apply your changes back to master
    • +
  • For this, we use git merge <branchToMerge> +
      +
    • It applies changes from <branchToMerge> to the current active branch
      • +
    +
    • +
  • master branch is usually (and should be) protected, so we can't merge our new code to master directly
    • +
  • Instead, we do the inverse.
    • +
+
+
+

Merging with a pull request

+
    +
  1. Make sure you have the newest version of the master branch:
    2. +
+
    +
  • Checkout master branch
    • +
  • Pull changes from GitHub/etc
    • +
  • Checkout the feature branch
    • +
  • Merge the contents of master to featureBranch with git merge master
    • +
+
    +
  1. Then, create a pull request on GitHub/etc (In GitLab, it's called merge request!)
    2. +
+
    +
  • This creates a formal process for merging your remote feature branch to remote master
    • +
  • This adds a layer of protection to the master branch: no direct merging!
    • +
+
+
+

+
    +
  • UI of a new pull request (Pull requests > New pull request) can be confusing... +
      +
    • base is the branch you're merging, compare is the branch you're merging into!
      • +
    +
    • +
+
+
+

If automatic merge fails...

+
    +
  1. Pull remote changes to your local master. +
      +
    • Pro tip: If you're on your feature branch, you can do this quickly without changing branches with
      +git fetch origin master:master
      • +
    +
    2. +
  2. Merge changes from master to your local feature branch.
    3. +
  3. Fix the ensuing conflicts (see next section)
    4. +
  4. Push your new local branch to GitHub/etc
    5. +
+
+
+

Extra: Merging without a pull request

+ +
    +
  1. First, checkout the master branch with git checkout master
    2. +
  2. Then, do a git pull so you have the newest version of the master branch +
      +
    • Someone else might have done changes to it while you were working on your feature!
      • +
    +
    3. +
  3. Then, merge <featureBranch> to master with git merge <featureBranch> +
      +
    • Fix conflicts
      • +
    +
    4. +
+
+
+

Exercise 1. Pushing onwards

+ +

Continue the exercise from Git Basics or create a new repository for these exercises.

+
    +
  • Create a new branch (with a name new-feature, for instance) in your local repository.
    • +
  • Checkout the branch, make some changes to GitTest.md there, and push the changes to GitHub.
    • +
  • Then, merge the changes from your new-feature branch to master branch by using
    +a) pull request in GitHub
    +b) git merge from command line
    • +
+
+
+

GitLens

+
    +
  • To make the Git workflow easier, install the GitLens extension to VS code +
      +
    • It helps in managing conflicts, comparing branches or commits
      • +
    +
    • +
  • Install it from the Extensions panel (access with CTRL+SHIFT+X)
    • +
  • Adds many new views to the source control tab: +
      +
    • Commits
      • +
    • Repositories
      • +
    • File History
      • +
    • Line History
      • +
    • Branches
      • +
    • Remotes
      • +
    • etc...
      • +
    +
    • +
+
+
+

3. Conflicts

+
+
+

Conflicts

+
    +
  • Sometimes two people have made changes in the same lines of code! +
      +
    • This leads to a conflict.
      • +
    +
    • +
  • Let's assume we're trying to merge changes from featureBranch to master.
    • +
  • If a conflict happens, the merge does not conclude automatically. Instead, we need to fix all the conflicts by hand and then conclude the merge with some commands.
    • +
  • Conflicting lines of code are framed by some <<<<<<< garbage ======= symbols >>>>>>> we don't yet understand
    • +
  • Before we can conclude the merge, we need to get rid of the garbage.
    • +
+
+
+

Said garbage

+
<<<<<<< HEAD:Player.cs
+  if (Input.anyKey) {
+    return true;
+  }
+=======
+  if (Input.anyKey)
+      return true;
+>>>>>>> featureBranch:Player.cs
+
+
    +
  • Current change is between <<<<<<< and =======: old code in master
    • +
  • Incoming change is between >>>>>>> and =======: new code from featureBranch
    • +
  • Use your text editor to choose which (or some combination of both) you want to preserve
    • +
+
+
+

VS Code tools

+
    +
  • VS Code gives us tools to make conflict resolution a quick process
    • +
  • Click which lines of code you want to preserve: +
      +
    • Accept Current Change (old code is preserved, new code removed)
      • +
    • Accept Incoming Change (new code is preserved, old code removed)
      • +
    • Accept Both Changes (both are preserved)
      • +
    +
    • +
+
+
+

After resolving the conflict

+
    +
  • After resolving conflicting files, use git add <filename> to add them to the commit
    • +
  • Then use git commit to apply changes (without a message! no -m) +
      +
    • Close the automatically opened COMMITMSG file. This should finish the merge.
      • +
    +
    • +
  • Then just git push to apply changes in the remote repository
    • +
+
If VS code is not configured properly as Git's text editor, and you encounter an error, run git config core.editor code --wait
+
+
+

Exercise 2. Fixing conflicts

+ +
    +
  • Create a new branch in your local repository, but do not checkout it just yet.
    • +
  • First, we simulate your teammate's changes by making changes to the master branch directly: On the master branch, make some changes to GitTest.md, and add & commit.
    • +
  • Then, checkout the new feature branch.
    • +
  • Then, make some other changes to GitTest.md to the same line as before, add & commit.
    • +
  • Then, merge the changes from the master branch to your feature branch by using git merge
    • +
  • Fix the ensuing conflicts, add & commit & push.
    • +
  • Now you can create a pull request to merge your changes to the master branch.
    • +
+
+
+

Git workflow 3: Undoing

+
    +
  • Git doesn't have a general "undo" command
    • +
  • If you make a mistake, it is very case-specific what you need to do to fix it + +
    • +
+
+
+

git log & git checkout <hashcode>

+
    +
  • +

    Use git log to see the commit history

    +
      +
    • Or git log --oneline for a more concise version
      • +
    • Press Q to quit the log view.
      • +
    • The newest changes are seen on top
      • +
    • On the left side of the commit message you see the hashcode of the commit
      • +
    • Use git checkout <hashcode> to "time travel" into the commit
      • +
    +
    • +
  • +

    Note: If you have GitLens, check the Commits view in the Source control tab to see the commit history.

    +
    • +
+
+
+

Revert one file to a previous state

+
    +
  • Sometimes you want to revert just one file to its previous state
    • +
  • For that, you need to figure out the commit hash of the state you want to return to
    • +
  • Find that out in one of the following methods: +
      +
    • git log --oneline
      • +
    • VS Code: Source control > File history
      • +
    • GitHub: check commits
      • +
    +
    • +
  • Then, run +
      +
    • git checkout <commit-hash> -- <filename>
      • +
    +
    • +
+
+
+

Collaboration in Unity

+
    +
  • The zeroth rule: Make sure that everyone on team uses the same Unity and package versions.
    • +
  • The first rule: Don't ever work on the same thing simultaneously.
    • +
  • The second rule: When you do break rule #1, make necessary changes in communication so you won't break it again.
    • +
  • Be sure to communicate about scene ownership +
      +
    • Scenes are not code files, so you can't easily merge changes if two people have worked on them
      • +
    • Thus, the Scene Owner will be the only person on the team who should be working on a certain scene
      • +
    • If a scene needs GameObject contributions from others, they can create prefabs that the Scene Owners then add to their scene
      • +
    +
    • +
+
+
+

Exercise 3. Branching team effort

+ +
    +
  • Work as a group for this assignment.
    • +
  • Continue Exercise 2 from Git basics.
    • +
  • Every group member creates an individual branch from the master, and makes some changes to the GitTest.md file.
    • +
  • Add new files as well, at least one per group member.
    • +
  • Do not tell other group members what you're going to change! :D
    • +
  • Then, merge the changes back to the master branch. Fix ensuing conflicts, if any appear.
    • +
+
+
+

Reading

+ +
+
+

Very extra: git rebase

+ +
    +
  • git merge creates a new commit for the merge process
    • +
  • Sometimes that's undesirable, so an alternative is to use git rebase
    • +
  • Unlike merge, rebase applies changes from the rebased branch one commit at a time
    • +
  • Whenever there's a conflict:
    • +
+
    +
  1. After fixing the conflict, add the conflicting file with git add <filename>
    2. +
  2. Then continue the rebase process with git rebase --continue
    3. +
  3. If you want to disregard a conflicting commit, use git rebase --skip
    4. +
  4. If you get cold feet, you can cancel the rebase with git rebase --abort
    5. +
+ +
+
+

Very very extra: Git submodules

+ +
    +
  • To add external code to your project from someone else's repository, Git has a neat system called submodules
    • +
  • To add a submodule to your project, use git submodule add <submodule-url> <folder>
    • +
  • To remove a submodule, use git rm <path-to-submodule>
    • +
  • If you clone a project with submodules, you need to run git submodule update --init --recursive once.
    • +
  • Note: If you don't want submodules to appear in the Source control tab of VS Code, go to settings and disable the Git: Detect Submodules setting.
    • +
+
+
\ No newline at end of file diff --git a/2-git-continued.md b/2-git-continued.md new file mode 100644 index 0000000..25b1ff2 --- /dev/null +++ b/2-git-continued.md @@ -0,0 +1,257 @@ +--- +title: Project management 2. Git continued +marp: true +paginate: true +theme: buutti +--- + + + +# Project management 2. Git continued + +## Branches + +* A Git repository can have multiple ***branches*** +* By default, a Git repository has only one branch + * named either `master` or `main` +* Using multiple branches makes it possible to work on new features step by step in their own ***feature branches*** + * Meanwhile, the `master` branch is kept clean and in a working state + * Only when the feature is completed, the branch is merged into the `master` branch! + +![bg right:30% width: 60%](imgs/git-branches.png) + +### Active branch + +* Even though your local repository can have multiple branches, only one of them is *active* at a given time +* `git status` tells you firsthand which branch you are on: `On branch master` + +## `git branch` & `git checkout` + +* You can create a new branch with `git branch ` + * The new branch is not empty: it contains a copy of the code of the branch you executed this command in +* ***Note:*** `git branch ` does not make the branch active! +* To make the branch active, a.k.a "move" to the branch: + * `git checkout `. + * For example, to move back to master use `git checkout master` + +### Local vs. remote branches + +* `git branch ` only creates a local branch +* When you try to push changes from a new local branch, Git nags you that a matching remote branch doesn't yet exist + * Git tells you how to create the remote branch: + * `git push --set-upstream origin ` + * Afterwards, `git push` pushes the changes to the matching remote branch + +### Extra branch commands + +* Handy command: `git checkout -b ` + * It's a shorthand for `git branch ` + `git checkout ` +* Get a list of local branches with `git branch` + * ...and all branches (incl. the remote ones) with `git branch -a` +* Delete a local branch with `git branch -d ` + * Remote branch can be deleted in the GitHub/etc website + * ...or with `git push origin -d ` + * ***Note:*** If deleted remote branches still show up in `git branch -a`, you can use the command `git remote prune origin` to remove them from the list. + +## `git merge` + +* So you've been working on a feature branch. What next? +* When the feature is done (and all the broken things fixed), you want to apply your changes back to `master` +* For this, we use `git merge ` + * It applies changes from `` to the ***current active branch*** +* `master` branch is usually (and should be) protected, so we can't merge our new code to `master` directly +* Instead, we do the *inverse*. + +## Merging with a pull request + +1) Make sure you have the newest version of the `master` branch: + * Checkout `master` branch + * Pull changes from GitHub/etc + * Checkout the feature branch + * Merge the contents of `master` to `featureBranch` with `git merge master` +2) Then, create a ***pull request*** on GitHub/etc (In GitLab, it's called ***merge request***!) + * This creates a formal process for merging your *remote* feature branch to remote `master` + * This adds a layer of protection to the `master` branch: no direct merging! + +--- + +![](imgs/github-pullreq.png) + +* UI of a new pull request (*Pull requests > New pull request*) can be confusing... + * *base* is the branch you're merging, *compare* is the branch you're merging into! + +### If automatic merge fails... + +1) Pull remote changes to your local `master`. + * ***Pro tip:*** If you're on your feature branch, you can do this quickly without changing branches with + ```git fetch origin master:master``` +2) Merge changes from `master` to your local feature branch. +3) Fix the ensuing ***conflicts*** (see [next section](#3-conflicts)) +4) Push your new local branch to GitHub/etc + +## Extra: Merging without a pull request + + +1) First, checkout the `master` branch with `git checkout master` +2) Then, do a `git pull` so you have the newest version of the `master` branch + * Someone else might have done changes to it while you were working on your feature! +3) Then, merge `` to `master` with `git merge ` + * Fix conflicts + +## Exercise 1. Pushing onwards + + +Continue the exercise from [Git Basics](1-git-basics) or create a new repository for these exercises. +* Create a new branch (with a name `new-feature`, for instance) in your local repository. +* Checkout the branch, make some changes to `GitTest.md` there, and push the changes to GitHub. +* Then, merge the changes from your `new-feature` branch to `master` branch by using + a) pull request in GitHub + b) `git merge` from command line + +## GitLens + +* To make the Git workflow easier, install the GitLens extension to VS code + * It helps in managing conflicts, comparing branches or commits +* Install it from the Extensions panel (access with ***CTRL+SHIFT+X***) +* Adds many new views to the source control tab: + * Commits + * Repositories + * File History + * Line History + * Branches + * Remotes + * etc... + +# 3. Conflicts + +## Conflicts + +* Sometimes two people have made changes in the same lines of code! + * This leads to a conflict. +* Let's assume we're trying to merge changes from featureBranch to master. +* If a conflict happens, the merge does not conclude automatically. Instead, we need to ***fix all the conflicts*** by hand and then ***conclude the merge*** with some commands. +* Conflicting lines of code are framed by some `<<<<<<< garbage ======= symbols >>>>>>>` we don't yet understand +* Before we can conclude the merge, we need to get rid of the garbage. + +### Said garbage + + ```c# + <<<<<<< HEAD:Player.cs + if (Input.anyKey) { + return true; + } + ======= + if (Input.anyKey) + return true; + >>>>>>> featureBranch:Player.cs + ``` +* ***Current change*** is between `<<<<<<<` and `=======`: old code in `master` +* ***Incoming change*** is between `>>>>>>>` and `=======`: new code from `featureBranch` +* Use your text editor to choose which (or some combination of both) you want to preserve + +### VS Code tools + +* VS Code gives us tools to make conflict resolution a quick process +* Click which lines of code you want to preserve: + * ***Accept Current Change*** (old code is preserved, new code removed) + * ***Accept Incoming Change*** (new code is preserved, old code removed) + * ***Accept Both Changes*** (both are preserved) + +![bg right width:95%](imgs/vscode-conflicts.png) + +## After resolving the conflict +* After resolving conflicting files, use `git add ` to add them to the commit +* Then use `git commit` to apply changes (without a message! no `-m`) + * Close the automatically opened `COMMITMSG` file. This should finish the merge. +* Then just `git push` to apply changes in the remote repository + + + +## Exercise 2. Fixing conflicts + + +* Create a new branch in your local repository, but do not checkout it just yet. +* First, we simulate your teammate's changes by making changes to the `master` branch directly: On the `master` branch, make some changes to `GitTest.md`, and **add & commit**. +* Then, checkout the new feature branch. +* Then, make some other changes to GitTest.md to the same line as before, **add & commit**. +* Then, merge the changes from the `master` branch to your feature branch by using `git merge` +* Fix the ensuing conflicts, add & commit & push. +* Now you can create a pull request to merge your changes to the master branch. + +## Git workflow 3: Undoing + +* Git doesn't have a general "undo" command +* If you make a mistake, it is very case-specific what you need to do to fix it + * See [undo options here](https://docs.gitlab.com/ee/topics/git/numerous_undo_possibilities_in_git/) + * Also, [ohshitgit.com](https://ohshitgit.com/) + +## `git log` & `git checkout ` + +* Use `git log` to see the commit history + * Or `git log --oneline` for a more concise version + * Press ***Q*** to quit the log view. + * The newest changes are seen on top + * On the left side of the commit message you see the ***hashcode*** of the commit + * Use `git checkout ` to "time travel" into the commit + +* ***Note:*** If you have GitLens, check the Commits view in the Source control tab to see the commit history. + +## Revert one file to a previous state + +* Sometimes you want to revert just one file to its previous state +* For that, you need to figure out the commit hash of the state you want to return to +* Find that out in one of the following methods: + * `git log --oneline` + * VS Code: *Source control > File history* + * GitHub: check commits +* Then, run + * `git checkout -- ` + +## Collaboration in Unity + +* ***The zeroth rule:*** Make sure that everyone on team uses the same Unity and package versions. +* ***The first rule:*** Don't ever work on the same thing simultaneously. +* ***The second rule:*** When you do break rule #1, make necessary changes in communication so you won't break it again. +* Be sure to communicate about ***scene ownership*** + * Scenes are not code files, so you can't easily merge changes if two people have worked on them + * Thus, the ***Scene Owner*** will be the only person on the team who should be working on a certain scene + * If a scene needs GameObject contributions from others, they can create prefabs that the Scene Owners then add to their scene + +## Exercise 3. Branching team effort + + +* Work as a group for this assignment. +* Continue Exercise 2 from [Git basics](1-git-basics). +* Every group member creates an individual branch from the master, and makes some changes to the `GitTest.md` file. +* Add new files as well, at least one per group member. +* Do not tell other group members what you're going to change! :D +* Then, merge the changes back to the master branch. Fix ensuing conflicts, if any appear. + +## Reading + +* [Pro Git book](https://git-scm.com/book/en/v2) +* [Oh shit Git](https://ohshitgit.com/) +* [Undo possibilities](https://docs.gitlab.com/ee/topics/git/numerous_undo_possibilities_in_git/) + +## Very extra: `git rebase` + + +* `git merge` creates a new commit for the merge process +* Sometimes that's undesirable, so an alternative is to use `git rebase` +* Unlike merge, rebase applies changes from the rebased branch ***one commit at a time*** +* Whenever there's a conflict: +1) After fixing the conflict, add the conflicting file with `git add ` +2) Then continue the rebase process with `git rebase --continue` +3) If you want to disregard a conflicting commit, use `git rebase --skip` +4) If you get cold feet, you can cancel the rebase with `git rebase --abort` + +* ***Note:*** A good link for [understanding rebase](https://borbware.github.io/unity-basics-course/project-management/2-git-continued-slides.html) + +## Very very extra: Git submodules + + +* To add external code to your project from someone else's repository, Git has a neat system called *submodules* +* To add a submodule to your project, use `git submodule add ` +* To remove a submodule, use `git rm ` +* If you clone a project with submodules, you need to run `git submodule update --init --recursive` once. +* ***Note:*** If you don't want submodules to appear in the Source control tab of VS Code, go to settings and disable the *Git: Detect Submodules* setting. \ No newline at end of file diff --git a/3-github-tools-slides.html b/3-github-tools-slides.html new file mode 100644 index 0000000..2c036e0 --- /dev/null +++ b/3-github-tools-slides.html @@ -0,0 +1,145 @@ +Project management 3. GitHub tools
+

Project management 3. GitHub tools

+
+
+

Issues

+
    +
  • Issues: tasks that need to be done +
      +
    • Use for sprint tasks!
      • +
    +
    • +
  • Creating a new issue +
      +
    • You can add a description
      • +
    • You can set an assignee to an issue
      • +
    • You can tag issue with a label +
        +
      • Feature, bug, code
        • +
      • level design, story...
        • +
      +
      • +
    • You can also link issue to a project
      • +
    +
    • +
  • When issue is done, you close it with Close issue
    • +
+
+
+
    +
  • Note: You can auto-close an issue with a commit message "fix #<issuenumber>" or "close #<issuenumber>"
    • +
  • Note: You can add todo lists into the description! +
      +
    • Todo list can include links to other issues (just write #issuenumber)
      • +
    • Don't create a mega-issue "Sprint 1" or something like that, however
      • +
    • We have a better tool for that...
      • +
    +
    • +
+
+
+

Projects

+
    +
  • A board that can be used to track sprint progress
    • +
  • GitHub has two Projects views +
      +
    • Projects +
        +
      • Under one repo
        • +
      +
      • +
    • Projects (Beta) +
        +
      • Can have issues from multiple repos
        • +
      +
      • +
    +
    • +
+
+
+
    +
  • Create a new project (not beta) for every sprint under Projects Tab > Projects (not beta!) > New Project +
      +
    • Give name "Sprint 1"
      • +
    • Use Project template "Automated kanban"
      • +
    • Delete the default notes
      • +
    +
    • +
  • Now, when an issue is closed, it jumps automatically to Done column
    • +
+
+
+
    +
  • Kanban board has by default three columns of issues & notes +
      +
    • To do
      • +
    • In Progress
      • +
    • Done
      • +
    +
    • +
  • There can be issues, pull requests and notes in the columns
    • +
  • Notes can be converted into issues
    • +
+
+
+

+
+
+

Pull requests

+
    +
  • The recommended way to merge a feature branch into the master branch
    • +
  • When a branch is ready to be merged into master, create a pull request in this tab
    • +
  • If the master branch maintainer doesn't accept it right away, they can comment on the pull request page what needs to be changed before merge can be completed
    • +
  • If "All comments need to be resolved" is checked, the merge can only be completed after you've addressed the issues and the maintainer has approved the changes!
    • +
  • After making these changes, you don't have to create a new pull request, new commits are automatically added to the one already created
    • +
+
+
+

+
+
+

Searching for specific issues and pull requests

+ +
+

## Actions + + + +## GitHub for Unity + +- a free Unity plugin +- makes communicating with GitHub easier and integrated into Unity

### Github + +* gotcha: logging into Github + * cannot use password anymore, you have to create a token for https. https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/#what-you-need-to-do-today + * repo, workflow, gist + + Collaboration tools + * Unity collab + * git

\ No newline at end of file diff --git a/3-github-tools.md b/3-github-tools.md new file mode 100644 index 0000000..26f2d80 --- /dev/null +++ b/3-github-tools.md @@ -0,0 +1,105 @@ +--- +title: Project management 3. GitHub tools +marp: true +paginate: true +theme: buutti +--- + + + +# Project management 3. GitHub tools + +## Issues + +* Issues: tasks that need to be done + * Use for sprint tasks! +* Creating a new issue + * You can add a description + * You can set an ***assignee*** to an issue + * You can tag issue with a ***label*** + * Feature, bug, code + * level design, story... + * You can also link issue to a ***project*** +* When issue is done, you close it with ***Close issue*** + +--- + +* ***Note:*** You can auto-close an issue with a commit message `"fix #"` or `"close #"` +* ***Note:*** You can add todo lists into the description! + * Todo list can include links to other issues (just write #issuenumber) + * Don't create a mega-issue "Sprint 1" or something like that, however + * We have a better tool for that... + +## Projects + +* A board that can be used to track sprint progress +* GitHub has two Projects views + * Projects + * Under one repo + * Projects (Beta) + * Can have issues from multiple repos + +--- + +* Create a new project (not beta) for every sprint under Projects Tab > Projects (not beta!) > New Project + * Give name "Sprint 1" + * Use Project template "Automated kanban" + * Delete the default notes +* Now, when an issue is closed, it jumps automatically to Done column + +--- + +* Kanban board has by default three columns of issues & notes + * To do + * In Progress + * Done +* There can be issues, pull requests and notes in the columns +* Notes can be converted into issues + +--- + +![](imgs/github-project.png) + +## Pull requests + +* The recommended way to merge a feature branch into the master branch +* When a branch is ready to be merged into master, create a pull request in this tab +* If the master branch maintainer doesn't accept it right away, they can comment on the pull request page what needs to be changed before merge can be completed +* If "All comments need to be resolved" is checked, the merge can only be completed after you've addressed the issues and the maintainer has approved the changes! +* After making these changes, you don't have to create a new pull request, new commits are automatically added to the one already created + +--- + +![](imgs/github-pullreq.png) + + +## Searching for specific issues and pull requests + +* You can search for issues or pull requests with specific dates, etc. +* The syntax is versatile, check these links for more info: + * [Searching issues and pull requests](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests#search-by-when-an-issue-or-pull-request-was-created-or-last-updated) + * [GitHub: Understanding the Search syntax](https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax) + + + + \ No newline at end of file diff --git a/4-scrum-slides.html b/4-scrum-slides.html new file mode 100644 index 0000000..2bea1ab --- /dev/null +++ b/4-scrum-slides.html @@ -0,0 +1,302 @@ +Project management 4. Scrum
+

Project management 4. Scrum

+
+
+

What is Scrum?

+
    +
  • Scrum is a framework for delivering products (usually software)
    • +
  • Designed for teams of ten or fewer members
    • +
  • Scrum Values +
      +
    • Minimal chance of failure: product is worked on in small increments
      • +
    • Transparency: changes are visible to the team
      • +
    +
    • +
  • Work is split to Sprints: goals that can be completed within time-constrained iterations +
      +
    • Sprints are most commonly two weeks long (for us, shorter)
      • +
    • Progress is tracked and re-planned in Dailies, 15-minute time-boxed meetings
      • +
    +
    • +
+
+
+

Why Scrum for game development?

+
    +
  • Through its practices and principles, Scrum creates conditions to achieve good results
    • +
  • Scrum gives agency to team members: meeting the goal is a team effort
    • +
  • Scrum creates transparency: problems get addressed early
    • +
  • Scrum isn't magic: you need to continuously enforce its practices in action
    • +
  • Scrum facilitates communication, but doesn't solve any problems for you!
    • +
+
+
+
    +
  • Cross-discipline teams: Enables teams to deliver features and mechanics that have clear value
    • +
  • Self-management: Enables teams to select the amount of work they can commit to every sprint and complete that work through whatever means they find appropriate
    • +
  • Self-organization: Enables teams to have a degree of authority and responsibility to select their membership
    • +
+
+
+

Scrum basics

+
+
+

Scrum people

+

+
+
+

Dev team

+
    +
  • Small team that aims to deliver a product
    • +
  • Organizes itself and its work
    • +
  • Collaborates with Product owner
    • +
  • Creates product increments in a series of sprints
    • +
+
+
+

Scrum master

+
    +
  • Helps to facilitate usage of Scrum to the team
    • +
  • Ensures the Scrum framework is followed
    • +
  • Aims to improve team's workflow +
      +
    • Basically an acting producer!
      • +
    +
    • +
  • Can be a part of the dev team (a "peer leader") +
      +
    • ...but should not be the product owner
      • +
    +
    • +
  • Can be a different person every Sprint
    • +
+
+
+

Product owner

+
    +
  • Accountable for profit & loss
    • +
  • Listens to the client's wishes
    • +
  • Manages the Product Backlog
    • +
  • Representation of stakeholders and clients to the Dev Team
    • +
  • Chooses what to release - and when
    • +
+
In this course, the teacher will act as this.
+
+
+

The rest

+
    +
  • Stakeholders (not actually part of the team) +
      +
    • People outside the Scrum team who have an interest in the product
      • +
    • Sales, marketing, end customers, etc
      • +
    +
    • +
  • Client +
      +
    • Monitors product backlog
      • +
    • Is responsible for the upkeep of the product backlog
      • +
    +
    • +
+
In this course, the teacher will act as these.
+
+
+

Backlogs

+
+
+

Product backlog

+
    +
  • Holds the requirements for the product
    • +
  • Managed by the Product Owner
    • +
  • Composed of tasks +
      +
    • unit of deliverable work
      • +
    • well-defined completeness
      • +
    • completable during a single Sprint
      • +
    • Features, Bugfixes, Content...
      • +
    +
    • +
+
+
+

+
+
+

Sprint backlog

+
    +
  • A list of tasks to be completed during the Sprint
    • +
  • Selected from the Product backlog
    • +
  • A forecast of what is aimed to be done during the Sprint, not a promise!!!
    • +
+
+
width:
+
+

Definition of Done

+
    +
  • When is a task considered done?
    • +
  • This is decided by the Dev team in Sprint Retrospective ("Retro")
    • +
  • Can change as project progresses +
      +
    • "It works" -> "It passes tests"
      • +
    +
    • +
+
+
+

Sprint Events

+
    +
  • First day: Sprint Planning
    • +
  • Every day: Daily Scrum
    • +
  • Last day: Sprint Review & Sprint Retrospective
    • +
+
+
+

Sprint planning

+
    +
  • Starts a new Sprint
    • +
  • The whole Scrum team attends +
      +
    • inspects the whole Product Backlog
      • +
    +
    • +
  • A Sprint Goal is created and dissected into a new Sprint Backlog +
      +
    • The Sprint Goal is immutable
      • +
    • The exact implementations are not discussed +
        +
      • those are rather left for the Dev Team to decide
        • +
      +
      • +
    +
    • +
  • New tasks are given to the Dev Team
    • +
+
+
+

Daily Scrum ("Daily")

+
    +
  • Only Dev Team attends, with these goals: +
      +
    • Inspect the progression towards the Sprint Goal
      • +
    • Inspect how the Sprint Backlog is clearing out
      • +
    • Create a plan for the next 24 hours
      • +
    +
    • +
  • Max. 15 min long!
    • +
  • Keeps everyone on the same page +
      +
    • Optimizes collaboration and performance of the Dev Team
      • +
    +
    • +
+
+
+
    +
  • Example topics to address in a Daily: +
      +
    • What have you achieved since the last Daily?
      • +
    • What problems have you faced?
      • +
    • How does the team address problems?
      • +
    • Is there need for (re)allocation of tasks?
      • +
    +
    • +
+
+
+

Sprint review

+
    +
  • Attended by the Scrum team and stakeholders
    • +
  • Goal: Offer feedback and open up discussions about the Sprint
    • +
  • Starts off with a feature demonstration
    • +
  • Product Owner presents the state of the Product Backlog +
      +
    • What is releasable?
      • +
    +
    • +
  • Dev Team tells what happened during the Sprint +
      +
    • How different problems were addressed?
      • +
    • What was their effect?
      • +
    +
    • +
  • Everybody provides and listens for feedback
    • +
+
+
+

Sprint retrospective ("Retro")

+
    +
  • After every Sprint Review
    • +
  • Only the Scrum team attends +
      +
    • worries and thoughts are brought up
      • +
    +
    • +
  • Possible discussion topics +
      +
    • What went right?
      • +
    • What should be improved?
      • +
    • Tools needed and used?
      • +
    • The suitability of the Scrum process.
      • +
    • What does Done mean, and should it be redefined?
      • +
    +
    • +
+
+
+

Scrum master tasks

+
    +
  • Continuously: +
      +
    1. Make sure the task board on GitHub is up to date.
      2. +
    2. Make sure everyone is able to attend the dailies.
      3. +
    3. Make sure everyone is heard and contributes at dailies.
      4. +
    4. If someone needs help, you help them find assistance or assist them yourself.
      5. +
    +
    • +
  • Before the dev meeting: +
      +
    1. Make sure the task board on GitHub is up to date.
      2. +
    2. Make sure someone is ready to present the newest working version of the program, with all the new changes pushed
      3. +
    3. Write down the state of tasks listed in the Sprint backlog
      4. +
    4. Discuss what problems were encountered during the last Sprint, and how were they addressed.
      5. +
    +
    • +
+
+

* ***True leadership***: Provides leadership focused on mentoring and facilitation to free the best performance possible from the team +## Cross-discipline teams +* Team members share the same goal and therefore the same priorities +* To make sure ***no work goes to waste***, synchronization of the disciplines happens every sprint. +* avoid one discipline getting too far ahead of the others! + +## Self-management +* No unnecessary management layers +* Scrum teams are usually composed of 5 to 9 cross-disciplined developers who create vertical slices of major features every sprint. +* How is this achieved? + * Choose the amount of work to accomplish for the coming sprint and commit to it + * Decide the best way to work together + * Every Daily: Estimate your own work and monitor progress toward a committed goal + * Every Sprint: Demonstrate sprint goals achieved to the stakeholders + * Take responsibility for performance and find ways to improve it + +## Self-organisation + +* Team selects their own members to complete tasks +* Some sprints, like before release, might require a complete reorganization

* "Fully completed" should refer to ***completely releasable***

\ No newline at end of file diff --git a/4-scrum.md b/4-scrum.md new file mode 100644 index 0000000..8250a3e --- /dev/null +++ b/4-scrum.md @@ -0,0 +1,209 @@ +--- +title: Project management 4. Scrum +marp: true +paginate: true +math: mathjax +theme: buutti +--- + + + +# Project management 4. Scrum + +## What is Scrum? + +* [Scrum](https://en.wikipedia.org/wiki/Scrum_(software_development)) is a framework for delivering products (usually software) +* Designed for teams of ten or fewer members +* Scrum Values + * ***Minimal chance of failure***: product is worked on in small increments + * ***Transparency***: changes are visible to the team +* Work is split to ***Sprints***: goals that can be completed within time-constrained iterations + * Sprints are most commonly two weeks long (for us, shorter) + * Progress is tracked and re-planned in ***Dailies***, 15-minute time-boxed meetings + +## Why Scrum for game development? + +* Through its practices and principles, Scrum creates ***conditions*** to achieve good results +* Scrum gives ***agency*** to team members: meeting the goal is a team effort +* Scrum creates ***transparency***: problems get addressed early +* Scrum isn't magic: you need to continuously enforce its practices in action +* Scrum facilitates communication, but doesn't solve any problems for you! + +--- + +* ***Cross-discipline teams***: Enables teams to deliver features and mechanics that have clear value +* ***Self-management***: Enables teams to select the amount of work they can commit to every sprint and complete that work through whatever means they find appropriate +* ***Self-organization***: Enables teams to have a degree of authority and responsibility to select their membership + + + +# Scrum basics + +## Scrum people + +![](imgs/scrum-people.png) + +### Dev team + +* Small team that aims to deliver a product +* Organizes itself and its work +* Collaborates with Product owner +* Creates product increments in a series of sprints + +### Scrum master + +* Helps to facilitate usage of Scrum to the team +* Ensures the Scrum framework is followed +* Aims to improve team's workflow + * Basically an acting producer! +* Can be a part of the dev team (a "peer leader") + * ...but should not be the product owner +* Can be a different person every Sprint + +### Product owner + +* Accountable for profit & loss +* Listens to the client's wishes +* Manages the Product Backlog +* Representation of stakeholders and clients to the Dev Team +* Chooses what to release - and when + + + +### The rest + +* Stakeholders (not actually part of the team) + * People outside the Scrum team who have an interest in the product + * Sales, marketing, end customers, etc +* Client + * Monitors product backlog + * Is responsible for the upkeep of the product backlog + + + +## Backlogs + +### Product backlog + +* Holds the requirements for the product +* Managed by the Product Owner +* Composed of ***tasks*** + * unit of deliverable work + * well-defined completeness + * completable during a single Sprint + * Features, Bugfixes, Content... + +--- +![](https://i.pinimg.com/originals/f8/6c/f4/f86cf4e5a8e7b0ab905ed53e8786aa28.png) + +### Sprint backlog + +* A list of tasks to be completed during the Sprint +* Selected from the Product backlog +* A *forecast* of what is aimed to be done during the Sprint, not a promise!!! + +--- + +![bg width: 80%](imgs/sprint-backlog.png) + +### Definition of Done + +* When is a task considered done? +* This is decided by the Dev team in Sprint ***Retrospective*** ("Retro") +* Can change as project progresses + * "It works" -> "It passes tests" + + + +## Sprint Events + +* First day: Sprint Planning +* Every day: Daily Scrum +* Last day: Sprint Review & Sprint Retrospective + +### Sprint planning + +* Starts a new Sprint +* The whole Scrum team attends + * inspects the whole Product Backlog +* A Sprint Goal is created and dissected into a new Sprint Backlog + * The Sprint Goal is ***immutable*** + * The exact implementations are not discussed + * those are rather left for the Dev Team to decide +* New tasks are given to the Dev Team + +### Daily Scrum ("Daily") + +* Only Dev Team attends, with these goals: + * Inspect the progression towards the Sprint Goal + * Inspect how the Sprint Backlog is clearing out + * Create a plan for the next 24 hours +* Max. 15 min long! +* Keeps everyone on the same page + * $\Rightarrow$ Optimizes collaboration and performance of the Dev Team + +--- + +* Example topics to address in a Daily: + * What have you achieved since the last Daily? + * What problems have you faced? + * How does the team address problems? + * Is there need for (re)allocation of tasks? + +### Sprint review + +* Attended by the Scrum team and stakeholders +* Goal: Offer feedback and open up discussions about the Sprint +* Starts off with a feature demonstration +* Product Owner presents the state of the Product Backlog + * What is releasable? +* Dev Team tells what happened during the Sprint + * How different problems were addressed? + * What was their effect? +* Everybody provides *and listens* for feedback + +### Sprint retrospective ("Retro") + +* After every Sprint Review +* Only the Scrum team attends + * worries and thoughts are brought up +* Possible discussion topics + * What went right? + * What should be improved? + * Tools needed and used? + * The suitability of the Scrum process. + * What does Done mean, and should it be redefined? + +## Scrum master tasks + +* Continuously: + 1. Make sure the task board on GitHub is up to date. + 2. Make sure everyone is able to attend the dailies. + 3. Make sure everyone is heard and contributes at dailies. + 4. If someone needs help, you help them find assistance or assist them yourself. +* Before the dev meeting: + 1. Make sure the task board on GitHub is up to date. + 2. Make sure someone is ready to present the newest working version of the program, with all the new changes pushed + 3. Write down the state of tasks listed in the Sprint backlog + 4. Discuss what problems were encountered during the last Sprint, and how were they addressed. diff --git a/README.md b/README.md index d2d9702..dfe2a23 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,13 @@ # Contents -Material completion denoted with 🌑🌘🌗🌖🌕 . - -| # | Lecture | Materials | Exercises | -| ---: | ------------------------------------- | --------: | --------: | -| 1 | [Example Lecture](example-lecture.md) | 🌕 | 🌕 | - - -## Repository notes (remove before publishing) - -- After reading, remove [example-lecture.md](./example-lecture.md), [example-lecture-slides.html](./example-lecture-slides.html) and [buuttilogo.png](./imgs/buuttilogo.png) -- See [Markdown code snippets](.vscode/markdown.code-snippets) for autocomplete stuff. -- Remove the .gitkeep files from imgs and solutions folders after adding new files to those folders. - -## Running scripts to convert lectures to MD - -Note: These instructions are for a Windows PC with WSL installed - -1) Install `pptx2md`: in an admin powershell, run `pip install pptx2md` -2) copy `.pptx` lecture slides to `.scripts` folder -3) In the `.scripts` folder, run `.\convertAndReplaceAll.bat` -4) If everything went ok, move the generated `.md` files and the `imgs` folder to the root folder -5) Remove .pptx files and the example lecture and its slides html -7) In the `.scripts` folder, run `python generateREADME.py` -8) Remove everything else from README than the generated table \ No newline at end of file +| # | Lecture | Slides | +|:--|:----------------------------------------------------------|:-----------------------------------------------------| +| 0 | [Project management 0. Git setup](0-git-setup.md) | [Download slides](0-git-setup-slides.html?raw=1) | +| 1 | [Project management 1. Git basics](1-git-basics.md) | [Download slides](1-git-basics-slides.html?raw=1) | +| 2 | [Project management 2. Git continued](2-git-continued.md) | [Download slides](2-git-continued-slides.html?raw=1) | +| | [Git cheat sheet](git-cheat-sheet.md) | [Download slides](git-cheat-sheet-slides.html?raw=1) | +| 3 | [Project management 3. GitHub tools](3-github-tools.md) | [Download slides](3-github-tools-slides.html?raw=1) | +| 4 | [Project management 4. Scrum](4-scrum.md) | [Download slides](4-scrum-slides.html?raw=1) | +| | [VS Code setup](vscode-setup.md) | [Download slides](vscode-setup-slides.html?raw=1) | +| | [Using VS Code](using-vscode.md) | [Download slides](using-vscode-slides.html?raw=1) | +| | [Best practices for programming](best-practices.md) | [Download slides](best-practices-slides.html?raw=1) | diff --git a/best-practices-slides.html b/best-practices-slides.html new file mode 100644 index 0000000..66518f1 --- /dev/null +++ b/best-practices-slides.html @@ -0,0 +1,447 @@ +Best practices for programming
+

Best practices for programming

+
+
+

Good programming

+
    +
  • You don't want to just learn programming
    • +
  • You want to learn how to program well
    • +
  • What is good code, then? +
      +
    • Let's go through some alarming examples
      • +
    • learn what ISN'T good code
      • +
    +
    • +
+
+
+

why make code good when bad code do job

+
    +
  • "I'll just hack this together quickly and move on" +
      +
    • A dangerous sentiment that will cost sweat, tears and person-hours
      • +
    • Every time I've thought this, I've either +
        +
      • a) had to eventually code it better
        • +
      • b) lost significant amount of time for deciphering later what the hell have I written
        • +
      +
      • +
    +
    • +
  • You always code for someone else +
      +
    • 1 - The compiler
      • +
    • 2 - Your teammates
      • +
    • 3 - You in the future +
        +
      • I can't stress this enough:
        • +
      • You in the future is a different person that you in the now.
        • +
      +
      • +
    +
    • +
+
+
+

The importance of whitespace

+
    +
  • The empty space & linebreaks have a huge impact on code readability
    • +
  • Alarming example:
    • +
+
        if (controller.MoveDirection != Vector3.zero)
+        {
+            controller.Move(controller.targetDirection, speed);
+                transform.rotation = Quaternion.LookRotation(controller.targetDirection);
+        }
+
+        if (!controller.isGrounded()) {
+                state=State.InAir;
+            }
+
+
+
+
+    if (jumpBuffer > 0)
+    {Jump();}
+
+
+
+
    +
  • Functionally, this is the same code, but much easier to read:
    • +
+
    if (controller.MoveDirection != Vector3.zero)
+    {
+        controller.Move(controller.targetDirection, KoiranNopeus);
+        transform.rotation = Quaternion.LookRotation(controller.targetDirection);
+    }
+
+    if (!controller.isGrounded())
+    {
+        state = State.InAir;
+    }
+
+    if (jumpBuffer > 0)
+    {
+        Jump();
+    }
+
+
+
+

In a nutshell...

+
    +
  • Indent only when introducing a new logical block (if, for loop, etc...)
    • +
  • Choose which style you use (spacebar / tab, how many spaces wide...) +
      +
    • ...and stick to it
      • +
    +
    • +
  • Use one empty line if you need to separate two blocks of code if needed
    • +
  • Make lines breathe: a = b + c;, not a=b+c;
    • +
  • Choose how you like to line { braces:
    if (true) {
+  ...
+}
+
    +or
    if (true)
+{
+  ...
+}
+
    +
    • +
+
+
+

Line width

+
    +
  • If your lines are getting too wide (over ~120 characters), split the code to multiple lines
    • +
  • As the lines get shorter, the code gets more readable
    • +
  • If you just do one thing per line, it's much easier to follow along
    • +
  • Example: refactor
    if (controller.MoveDirection != Vector3.zero && !controller.isGrounded() && jumpBuffer > 0)
+
    +to
    if (controller.MoveDirection != Vector3.zero
+  && !controller.isGrounded()
+  && jumpBuffer > 0)
+
    +
    • +
+
Some programmers prefer line widths of 100 or even 80 characters.
+
+
+

But we can go further

+
    +
  • Do not try to minimize code size
    • +
  • Rather try to maximize debuggability
    • +
  • This can usually happen by introducing "redundant" variables. Consider
    if (controller.MoveDirection != Vector3.zero
+  && !controller.isGrounded()
+  && jumpBuffer > 0)
+
    +
    • +
  • vs.
    const bool notMoving = controller.MoveDirection != Vector3.zero;
+const bool onAir = !controller.isGrounded();
+const bool canJump = jumpBuffer > 0;
+
+if (notMoving && onAir && canJump)
+
    +
    • +
+
+
+

Commenting just enough

+
    +
  • It can be difficult to decide what's the correct amount of commenting
    • +
  • Comments should explain what the code does
    • +
  • ...if and only if the code does not already explain that!
    // set player state to grounded when player touches the ground
+if (collider.tag == "Ground")
+{
+  const state = State.Grounded;
+}
+
    +
    • +
  • The comment above provides almost zero new information
    • +
+
+
+

Commenting with function calls

+
    +
  • In some cases, a better way to explain the code is to wrap it into a small helper function
    // give a random rotation between 0 and 180
+const rotation = Quaternion.Euler(0, Random.Range(0, 180), 0);
+
    +
    • +
  • Instead, what about this:
     public static Quaternion RandomRotationRange(float angle1, float angle2)
+ {
+     return Quaternion.Euler(0, Random.Range(angle1, angle2), 0);
+ }
+
    +a) it gives the same information you wanted to give
    +b) it's now more reusable
    +c) it hides the implementation, so when we read the code, we can focus on the WHAT instead of the HOW
    • +
+
+
+

Naming variables

+
    +
  • Wikipedia: Naming convention
    • +
  • "There are two hard things in computer science: cache invalidation, naming things, and off-by-one errors."
    • +
  • For real, naming is one of the hardest tasks in programming.
    • +
  • It's all about communicating enough, but not too much
    • +
  • First rule: Explain what the variable stores! +
      +
    • a) a = b * c; +
        +
      • I have no idea what this line is really doing
        • +
      +
      • +
    • b) weeklyPay = hoursWorked * hourlyPayRate; +
        +
      • That's more like it!
        • +
      +
      • +
    +
    • +
+
+
+
    +
  • How would you name a variable that stores what is the probability for player's attack to land? +
      +
    • pAttack, attackLandProbability, player1HitPercentage... +
        +
      • None of these are exceptionally good
        • +
      +
      • +
    • Good variable names are always case-specific: +
        +
      • Sometimes you can go too descriptive... +
          +
        • playerAttackToLandProbabilityAsPercentage
          • +
        +
        • +
      • However! It's much more usual to go not descriptive enough +
          +
        • pAtk
          • +
        +
        • +
      • The golden route is somewhere in the middle!
        • +
      +
      • +
    +
    • +
+
+
+

Get rid of magic numbers!

+
    +
  • Consider this:
    rotationsPerDay = rotationsPerSecond * 60 * 60 * 24;
+
    +
    • +
  • Vs. this:
    secondsPerDay = 60 * 60 * 24;
+rotationsPerDay = rotationsPerSecond * secondsPerDay;
+
    +
    • +
  • This might seem like stating the obvious, but we usually want to do this! +
      +
    • What may seem obvious to you, might not be to the reader of the code
      • +
    • ...which will be you one day
      • +
    +
    • +
+
+
+

Write what you mean

+
    +
  • This concerns not only variable naming, but also how to generally use statements
    • +
  • Do not leave anything implied - write what you mean explicitly
    • +
  • Let's have an innocious yet dangerous example: +
      +
    • Consider a player character that has two states, Jump and Idle.
      • +
    • We could play the animations as thus:
      if (state == PlayerState.Jump)
+{
+  JumpAnimation.Play();
+} else {
+  IdleAnimation.Play();
+}
+
      +
      • +
    • However! What if the player gets a Swim state in the future?
      • +
    • Now the else block has to be refactored!
      • +
    • What if this implicit idea of "else equals idle" is present in multiple places?
      • +
    +
    • +
+
+
+
    +
  • State your intent!
    if (state == PlayerState.Jump)
+{
+  JumpAnimation.Play();
+}
+else if (state == PlayerState.Idle)
+{
+  IdleAnimation.Play();
+}
+
    +
    • +
+
+
+

Dangers of overgeneralization

+
    +
  • Sometimes you might think it's smart to account for possible future use cases
    • +
  • This leads to unnecessary complexity: you have code that is there just IN CASE
    • +
  • The problem is, you usually can't know beforehand what use cases are actually needed +
      +
    • Actually, it's downright impossible to predict what structure is optimal for your use case
      • +
    • After you have created the structure, you know what kind of structure you should have written
      • +
    +
    • +
  • Write code that solves the problem you have, not some problem you might possibly have in the future!
    • +
+
+
+

Be cohesive!

+
    +
  • If you write one variable in a certain way, be sure to use that style for other variables as well
    • +
  • Alarming example:
    int spr_smallhop = 993,
+bool drwOnAbove = true;
+int[] shinypals = [ 1, 4, 2 ];
+
    +
      +
    • three different variables, three different casings +
        +
      • snake_case
        • +
      • camelCase
        • +
      • flatcase
        • +
      +
      • +
    +
    • +
+
+
+

Bad structure

+
    +
  • When do you have bad structure in your code?
    • +
  • Cases of code smell: +
      +
    • When changing one thing in code, you have to change something completely unrelated to make it work.
      • +
    • When writing/reading code, you have to jump between code files constantly.
      • +
    • You need to reread lines of code again and again to understand what's going on
      • +
    • Everything breaks if the code isn't used in a very specific manner
      • +
    +
    • +
  • Wikipedia: Anti-pattern
    • +
  • Wikipedia: Code smell
    • +
+
+
+

How does bad structure happen?

+
    +
  • No one wants to deliberately write bad code +
      +
    • The "I'll just hack this quickly" mentality can sometimes be to blame
      • +
    • also, the lack of concern for readability
      • +
    +
    • +
  • ...but more often, bad structure happens over a longer period of time +
      +
    • First, you code a feature X
      • +
    • You extend the code with a feature Y
      • +
    • then accommodate for a use case Z
      • +
    • Then you notice X isn't really needed any more
      • +
    • Too late, structure bad!
      • +
    +
    • +
  • Sometimes the only way to fix this is to refactor the whole structure from scratch +
      +
    • Very often the only way to know how you should have done it is to do it wrong first!
      • +
    +
    • +
+
+
+

Some principles for better structure

+ +
+
+

But beware!

+
    +
  • Even following the principles shown can lead to bad code
    • +
  • An experienced programmer can decide for themselves, when they should use them
    • +
  • For example, creating two almost identical functions than creating a single function that covers two almost identical cases might sometimes result in much easier-to-read code +
      +
    • It's yours to decide when that "sometimes" holds true
      • +
    +
    • +
+
+
+

Conclusions

+
+
+

What makes code good?

+
    +
  • Good code is... +
      +
    • readable
      • +
    • pretty
      • +
    • self-consistent
      • +
    • self-explanatory
      • +
    • well-contained
      • +
    • reusable (to some extent)
      • +
    +
    • +
+
+
+

Extra: Linters

+ +
    +
  • "You can use linters to format code automatically
    • +
  • Here's a guide to C# formatting with ESLint, a popular linter
    • +
+
+
+

Reading

+ +
+
\ No newline at end of file diff --git a/best-practices.md b/best-practices.md new file mode 100644 index 0000000..b15bf45 --- /dev/null +++ b/best-practices.md @@ -0,0 +1,328 @@ +--- +marp: true +paginate: true +title: Best practices for programming +math: mathjax +theme: buutti +--- + + + +# Best practices for programming + +## Good programming + +* You don't want to just learn programming +* You want to learn how to program ***well*** +* What is good code, then? + * Let's go through some alarming examples + * $\Rightarrow$ learn what ISN'T good code + +## why make code good when bad code do job + +* "I'll just hack this together quickly and move on" + * A dangerous sentiment that ***will*** cost sweat, tears and person-hours + * Every time I've thought this, I've either + * a) had to eventually code it better + * b) lost significant amount of time for deciphering later what the hell have I written +* *You always code for someone else* + * 1 - The compiler + * 2 - Your teammates + * 3 - You in the future + * I can't stress this enough: + * *You in the future is a different person that you in the now.* + +## The importance of whitespace + +* The ***empty space*** & ***linebreaks*** have a huge impact on code readability +* Alarming example: +```c# + if (controller.MoveDirection != Vector3.zero) + { + controller.Move(controller.targetDirection, speed); + transform.rotation = Quaternion.LookRotation(controller.targetDirection); + } + + if (!controller.isGrounded()) { + state=State.InAir; + } + + + + + if (jumpBuffer > 0) + {Jump();} +``` + +--- + +* Functionally, this is the same code, but ***much*** easier to read: + +```c# + if (controller.MoveDirection != Vector3.zero) + { + controller.Move(controller.targetDirection, KoiranNopeus); + transform.rotation = Quaternion.LookRotation(controller.targetDirection); + } + + if (!controller.isGrounded()) + { + state = State.InAir; + } + + if (jumpBuffer > 0) + { + Jump(); + } +``` + +### In a nutshell... + +* Indent only when introducing a new logical block (if, for loop, etc...) +* Choose which style you use (spacebar / tab, how many spaces wide...) + * ...and ***stick to it*** +* Use ***one*** empty line if you need to separate two blocks of code if needed +* Make lines breathe: `a = b + c;`, not `a=b+c;` +* Choose how you like to line `{` braces: + ```c# + if (true) { + ... + } + ``` + or + ```c# + if (true) + { + ... + } + ``` + +## Line width + +* If your lines are getting too wide (over ~120 characters), split the code to multiple lines +* As the lines get shorter, the code gets more readable +* If you just do one thing per line, it's much easier to follow along +* Example: refactor + ```c# + if (controller.MoveDirection != Vector3.zero && !controller.isGrounded() && jumpBuffer > 0) + ``` + to + ```c# + if (controller.MoveDirection != Vector3.zero + && !controller.isGrounded() + && jumpBuffer > 0) + ``` + + +### But we can go further + +* Do not try to minimize code size +* Rather try to maximize *debuggability* +* This can usually happen by introducing "redundant" variables. Consider + ```c# + if (controller.MoveDirection != Vector3.zero + && !controller.isGrounded() + && jumpBuffer > 0) + ``` +* vs. + ```c# + const bool notMoving = controller.MoveDirection != Vector3.zero; + const bool onAir = !controller.isGrounded(); + const bool canJump = jumpBuffer > 0; + + if (notMoving && onAir && canJump) + ``` + +## Commenting just enough + +* It can be difficult to decide what's the correct amount of commenting +* Comments should explain what the code does +* ...if and only if the code does not already explain that! + ```c# + // set player state to grounded when player touches the ground + if (collider.tag == "Ground") + { + const state = State.Grounded; + } + ``` +* The comment above provides almost zero new information + +### Commenting with function calls + +* In some cases, a better way to explain the code is to wrap it into a small helper function + ```c# + // give a random rotation between 0 and 180 + const rotation = Quaternion.Euler(0, Random.Range(0, 180), 0); + ``` +* Instead, what about this: + ```c# + public static Quaternion RandomRotationRange(float angle1, float angle2) + { + return Quaternion.Euler(0, Random.Range(angle1, angle2), 0); + } + ``` + a) it gives the same information you wanted to give + b) it's now more reusable + c) it hides the implementation, so when we read the code, we can focus on the WHAT instead of the HOW + +## Naming variables + +* [Wikipedia: Naming convention](https://en.wikipedia.org/wiki/Naming_convention_(programming)) +* *"There are two hard things in computer science: cache invalidation, naming things, and off-by-one errors."* +* For real, naming is one of the hardest tasks in programming. +* It's all about communicating enough, but not too much +* First rule: Explain what the variable stores! + * a) `a = b * c;` + * I have no idea what this line is *really* doing + * b) `weeklyPay = hoursWorked * hourlyPayRate;` + * That's more like it! + +--- + +* How would you name a variable that stores what is the probability for player's attack to land? + * `pAttack`, `attackLandProbability`, `player1HitPercentage`... + * None of these are exceptionally good + * Good variable names are always case-specific: + * Sometimes you can go too descriptive... + * `playerAttackToLandProbabilityAsPercentage` + * However! It's much more usual to go ***not descriptive enough*** + * `pAtk` + * The golden route is somewhere in the middle! + + +## Get rid of magic numbers! + +* Consider this: + ```c# + rotationsPerDay = rotationsPerSecond * 60 * 60 * 24; + ``` +* Vs. this: + ```c# + secondsPerDay = 60 * 60 * 24; + rotationsPerDay = rotationsPerSecond * secondsPerDay; + ``` +* This might seem like stating the obvious, but we usually want to do this! + * What may seem obvious to you, might not be to the reader of the code + * ...which will be you one day + +## Write what you mean + +* This concerns not only variable naming, but also how to generally use statements +* Do not leave anything implied - write what you mean ***explicitly*** +* Let's have an innocious yet dangerous example: + * Consider a player character that has two states, `Jump` and `Idle`. + * We could play the animations as thus: + ```c# + if (state == PlayerState.Jump) + { + JumpAnimation.Play(); + } else { + IdleAnimation.Play(); + } + ``` + * However! What if the player gets a `Swim` state in the future? + * Now the `else` block has to be refactored! + * What if this implicit idea of "else equals idle" is present in multiple places? + +--- + +* State your intent! + ```c# + if (state == PlayerState.Jump) + { + JumpAnimation.Play(); + } + else if (state == PlayerState.Idle) + { + IdleAnimation.Play(); + } + ``` + +## Dangers of overgeneralization + +* Sometimes you might think it's smart to account for possible future use cases +* This leads to unnecessary complexity: you have code that is there just IN CASE +* The problem is, you usually can't know beforehand what use cases are actually needed + * Actually, it's downright impossible to predict what structure is optimal for your use case + * After you have created the structure, you know what kind of structure you should have written +* Write code that solves the problem you have, not some problem you might possibly have in the future! + +## Be cohesive! + +* If you write one variable in a certain way, be sure to use that style for other variables as well +* Alarming example: + ```c# + int spr_smallhop = 993, + bool drwOnAbove = true; + int[] shinypals = [ 1, 4, 2 ]; + ``` + * three different variables, three different casings + * `snake_case` + * `camelCase` + * `flatcase` + +## Bad structure + +* When do you have bad *structure* in your code? +* Cases of *code smell*: + * When changing one thing in code, you have to change something completely unrelated to make it work. + * When writing/reading code, you have to jump between code files constantly. + * You need to reread lines of code again and again to understand what's going on + * Everything breaks if the code isn't used in a very specific manner +* [Wikipedia: Anti-pattern](https://en.wikipedia.org/wiki/Anti-pattern) +* [Wikipedia: Code smell](https://en.wikipedia.org/wiki/Code_smell) + +### How does bad structure happen? + +* No one wants to deliberately write bad code + * The "I'll just hack this quickly" mentality can sometimes be to blame + * also, the lack of concern for readability +* ...but more often, bad structure happens over a longer period of time + * First, you code a feature X + * You extend the code with a feature Y + * then accommodate for a use case Z + * Then you notice X isn't really needed any more + * Too late, structure bad! +* Sometimes the only way to fix this is to refactor the whole structure from scratch + * Very often the only way to know how you ***should*** have done it is to do it wrong first! + +## Some principles for better structure + +* [Separation of concerns](https://en.wikipedia.org/wiki/Separation_of_concerns): + * One part of code (function, class...) handles only one thing +* [Locality of behaviour](https://htmx.org/essays/locality-of-behaviour/) + * You can understand a concept by looking at a small portion of source code +* [DRY: Don't repeat yourself](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) + * If you write a duplicate of previously-written ~10 lines of code with minimal changes, you might have a problem + * Better idea to wrap it into a function +* [KISS: Keep it simple, stupid](https://en.wikipedia.org/wiki/KISS_principle) + * Complexity bad + +### But beware! + +* Even following the principles shown can lead to bad code +* An experienced programmer can decide for themselves, when they should use them +* For example, creating two almost identical functions than creating a single function that covers two almost identical cases might sometimes result in much easier-to-read code + * It's yours to decide when that "sometimes" holds true + +# Conclusions + +## What makes code good? + +* Good code is... + * readable + * pretty + * self-consistent + * self-explanatory + * well-contained + * reusable (to some extent) + +### Extra: Linters + + +* "You can use [linters](https://en.wikipedia.org/wiki/Lint_(software)) to format code automatically +* [Here's](https://johnnyreilly.com/eslint-your-csharp-in-vs-code-with-roslyn-analyzers) a guide to C# formatting with ESLint, a popular linter + +## Reading + +* [The Grug Brained Developer: A layman's guide to thinking like the self-aware smol brained](https://grugbrain.dev/) \ No newline at end of file diff --git a/example-lecture.md b/example-lecture.md deleted file mode 100644 index 6c11c6d..0000000 --- a/example-lecture.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -marp: true -paginate: true -math: mathjax -theme: buutti -title: N. Example Lecture ---- - -# Example Lecture - - - - -## Section - -- This line appears instantly -* This line appears by pressing spacebar (preferred) -* This line has an inline code `variable` -1. This line appears instantly -2) This line appears by pressing spacebar - -## Code and maths - -* code code code: - ```js - console.log("Here's a syntax-highlighted JavaScript code block"); - console.log("Remember indentation so it's revealed after the bullet point."); - ``` -* This line has an inline LaTeX maths equation $c = \frac{a^2}{\sqrt{b}}$ -* Here's a maths block: - -$$ -F(x) = \int_a^b f(x) dx -$$ - - - -## Columns - -
-
- -![](imgs/buuttilogo.png) - -* Basic image example - -
-
- -![width:800px](imgs/buuttilogo.png) -* Wider image - -
-
- -* This line is outside the columns and goes from left all the way to the right - -## Columns 2 - -
-
- -* Another column example with a wider left panel - -
-
- -* Change `class` name to change proportions -* If suitable proportions not available, add to `buutti.css` - -
-
- -## Setup - -* In VS Code, install the extensions - * [Marp for VS code](https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode) - * So you can see the slideshow preview when editing. - * [Markdown all in one](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) - * [Markdown table formatter](https://marketplace.visualstudio.com/items?itemName=fcrespo82.markdown-table-formatter) - * *Right click > Format document* makes tables pretty - * [Save and run](https://marketplace.visualstudio.com/items?itemName=wk-j.save-and-run) - * An HTML version of the lecture is created on save - * See [settings.json](./.vscode/settings.json) - * Add filenames to `notMatch` if a HTML on save is not needed \ No newline at end of file diff --git a/example-lecture-slides.html b/git-cheat-sheet-slides.html similarity index 65% rename from example-lecture-slides.html rename to git-cheat-sheet-slides.html index dcc8159..f8bd2e6 100644 --- a/example-lecture-slides.html +++ b/git-cheat-sheet-slides.html @@ -1,4 +1,4 @@ -N. Example Lecture
-

Example Lecture

+/* @theme 3uonzff0y2cnc5g7qge2ddr3624o7vgq4i9ynpodr0q */div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background=background]{columns:initial!important;display:block!important;padding:0!important}div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background=background]:after,div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background=background]:before,div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background=content]:after,div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background=content]:before{display:none!important}div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background=background]>div[data-marpit-advanced-background-container]{all:initial;display:flex;flex-direction:row;height:100%;overflow:hidden;width:100%}div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background=background]>div[data-marpit-advanced-background-container][data-marpit-advanced-background-direction=vertical]{flex-direction:column}div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background=background][data-marpit-advanced-background-split]>div[data-marpit-advanced-background-container]{width:var(--marpit-advanced-background-split,50%)}div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background=background][data-marpit-advanced-background-split=right]>div[data-marpit-advanced-background-container]{margin-left:calc(100% - var(--marpit-advanced-background-split, 50%))}div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background=background]>div[data-marpit-advanced-background-container]>figure{all:initial;background-position:center;background-repeat:no-repeat;background-size:cover;flex:auto;margin:0}div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background=background]>div[data-marpit-advanced-background-container]>figure>figcaption{position:absolute;border:0;clip:rect(0,0,0,0);height:1px;margin:-1px;overflow:hidden;padding:0;white-space:nowrap;width:1px}div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background=content],div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background=pseudo]{background:transparent!important}div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background=pseudo],div#\:\$p>svg[data-marpit-svg]>foreignObject[data-marpit-advanced-background=pseudo]{pointer-events:none!important}div#\:\$p>svg>foreignObject>section[data-marpit-advanced-background-split]{width:100%;height:100%}
+

Git cheat sheet

-
-

Section

-
    -
  • This line appears instantly
    • -
-
    -
  • This line appears by pressing spacebar (preferred)
    • -
  • This line has an inline code variable
    • -
-
    -
  1. This line appears instantly
    2. -
-
    -
  1. This line appears by pressing spacebar
    2. -
+
+

Uploading a new Unity project to GitHub

+

Initialize Git in the Unity project folder, pull the .gitignore file, make your first commit and push:

+

git init

+

git remote add origin [remote-url]

+

git pull origin main

+

git add .

+

git commit -m "first commit"

+

git push --set-upstream origin main

-
-

Code and maths

-
    -
  • code code code:
    console.log("Here's a syntax-highlighted JavaScript code block");
-console.log("Remember indentation so it's revealed after the bullet point.");
-
    -
    • -
  • This line has an inline LaTeX maths equation
    • -
  • Here's a maths block:
    • -
-

Footers are exclusive to presentation; they are not shown in the webpage markdown document
+
+

Common workflow

+

git status

+

git add filename

+

git commit -m "make change"

+

git pull (If working in a team, always pull before pushing!)

+

git push

-
-

Columns

-
-
-

-
    -
  • Basic image example
    • -
-
-
-

+
+

Creating a new branch

+

git checkout -b newBranch

    -
  • Wider image
    • +
  • This is a shorthand for git branch newBranch && git checkout newBranch
- - +

git add newFile.txt

+

git commit -m "add newFile.txt"

+

git push --set-upstream origin newBranch

    -
  • This line is outside the columns and goes from left all the way to the right
    • +
  • (The line above creates a new remote branch. After doing it once, you can just use regular git push)
-
-

Columns 2

-
-
-
    -
  • Another column example with a wider left panel
    • -
-
-
+
+

Merging a feature branch to master

+

git checkout master

+

git merge newBranch

    -
  • Change class name to change proportions
    • -
  • If suitable proportions not available, add to buutti.css
    • +
  • This is where the conflicts happen. Fix them in VS code
- - +

git add conflictedFile.txt

+

git commit

+

git push

-
-

Setup

+
+

Merging changes from master to feature branch

+
+

Reading

    -
  • An HTML version of the lecture is created on save
    • -
  • See settings.json
    • -
  • Add filenames to notMatch if a HTML on save is not needed
    • -
- - - +
  • GitHub cheat sheet
    •  \ No newline at end of file diff --git a/git-rebase.md b/git-rebase.md new file mode 100644 index 0000000..9ace020 --- /dev/null +++ b/git-rebase.md @@ -0,0 +1,63 @@ +--- +title: Project management. Git rebase +marp: true +paginate: true +theme: buutti +--- + + + +# Project management. Git Rebase (WIP) + +## extra + +muista: +`git push --force-with-lease` + +VS Code: git branch view + +## kunnon tapa commitoida + +* title & body + +* vs code settings: + * commit viesti blockki fontti + * pystyviiva estämään liian pitkät + * push & pull napit + +## wip commits + +* wip commits +* then `git reset master` ja teet uuen kunnon commitin +* mut mitä jos tää ei riitä? + +## Git Rebase + +* rewrite your local Git history before merging your private branch to master +* "replays" your commits + +`git rebase -i commit_before_start` +* commands + * pick + * reword + * fixup + * edit +* Explained when interactive rebase starts + +--- + +* käy läpi muutokset branchi-viewistä käsin, laita uudet committiviestit ylös johonki esim notepad ja merkkaa mitä komentoa käytät mihinki +* `git merge —ff-only` + +* obs: if you've merged something from master to this branch somewhere in the middle, rebase fails + +## Extra: splitting a commit + +* Want to split one commit to many, or move changes from one commit to another? +* Use interactive rebase like [this](https://stackoverflow.com/questions/6217156/break-a-previous-commit-into-multiple-commits) + * Start an interactive rebase with `git rebase -i ^` + * Mark the commit you want to split with the action `edit`. + * When editing said commit, execute `git reset HEAD^`. The effect is that the files of said commit are unstaged now. + * Add the changes to a new commit with `git add`, then commit with `git commit`. Repeat until working tree is clean. + * Continue with `git rebase --continue` +* After this rebase, if you want to combine commits, you can do it with another rebase \ No newline at end of file diff --git a/imgs/.gitkeep b/imgs/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/imgs/buuttilogo.png b/imgs/buuttilogo.png deleted file mode 100644 index 8c35578..0000000 Binary files a/imgs/buuttilogo.png and /dev/null differ diff --git a/imgs/git-branches.png b/imgs/git-branches.png new file mode 100644 index 0000000..b6521b8 Binary files /dev/null and b/imgs/git-branches.png differ diff --git a/imgs/git-status.png b/imgs/git-status.png new file mode 100644 index 0000000..ad553da Binary files /dev/null and b/imgs/git-status.png differ diff --git a/imgs/git1.png b/imgs/git1.png new file mode 100644 index 0000000..eddc6a8 Binary files /dev/null and b/imgs/git1.png differ diff --git a/imgs/git2.png b/imgs/git2.png new file mode 100644 index 0000000..2504fc3 Binary files /dev/null and b/imgs/git2.png differ diff --git a/imgs/git3.png b/imgs/git3.png new file mode 100644 index 0000000..e03f73f Binary files /dev/null and b/imgs/git3.png differ diff --git a/imgs/git4.png b/imgs/git4.png new file mode 100644 index 0000000..25d52fa Binary files /dev/null and b/imgs/git4.png differ diff --git a/imgs/git5.png b/imgs/git5.png new file mode 100644 index 0000000..4459e4f Binary files /dev/null and b/imgs/git5.png differ diff --git a/imgs/git6.png b/imgs/git6.png new file mode 100644 index 0000000..19cdf59 Binary files /dev/null and b/imgs/git6.png differ diff --git a/imgs/git7.png b/imgs/git7.png new file mode 100644 index 0000000..fc7b62e Binary files /dev/null and b/imgs/git7.png differ diff --git a/imgs/git8.png b/imgs/git8.png new file mode 100644 index 0000000..ab52d32 Binary files /dev/null and b/imgs/git8.png differ diff --git a/imgs/github-project.png b/imgs/github-project.png new file mode 100644 index 0000000..1c572b7 Binary files /dev/null and b/imgs/github-project.png differ diff --git a/imgs/github-pullreq.png b/imgs/github-pullreq.png new file mode 100644 index 0000000..acba25d Binary files /dev/null and b/imgs/github-pullreq.png differ diff --git a/imgs/hover-over-method.png b/imgs/hover-over-method.png new file mode 100644 index 0000000..5ea2ec3 Binary files /dev/null and b/imgs/hover-over-method.png differ diff --git a/imgs/references.png b/imgs/references.png new file mode 100644 index 0000000..c4053a1 Binary files /dev/null and b/imgs/references.png differ diff --git a/imgs/scrum-people.png b/imgs/scrum-people.png new file mode 100644 index 0000000..bbfbf5c Binary files /dev/null and b/imgs/scrum-people.png differ diff --git a/imgs/sprint-backlog.png b/imgs/sprint-backlog.png new file mode 100644 index 0000000..12380c0 Binary files /dev/null and b/imgs/sprint-backlog.png differ diff --git a/imgs/vscode-conflict2.png b/imgs/vscode-conflict2.png new file mode 100644 index 0000000..e531a91 Binary files /dev/null and b/imgs/vscode-conflict2.png differ diff --git a/imgs/vscode-conflicts.png b/imgs/vscode-conflicts.png new file mode 100644 index 0000000..3eb1b8e Binary files /dev/null and b/imgs/vscode-conflicts.png differ diff --git a/imgs/vscode-editor.png b/imgs/vscode-editor.png new file mode 100644 index 0000000..8b409da Binary files /dev/null and b/imgs/vscode-editor.png differ diff --git a/imgs/vscode-explorer.png b/imgs/vscode-explorer.png new file mode 100644 index 0000000..a71f8a7 Binary files /dev/null and b/imgs/vscode-explorer.png differ diff --git a/imgs/vscode-installation.png b/imgs/vscode-installation.png new file mode 100644 index 0000000..e667822 Binary files /dev/null and b/imgs/vscode-installation.png differ diff --git a/imgs/vscode-marp-preview.png b/imgs/vscode-marp-preview.png new file mode 100644 index 0000000..8dcb758 Binary files /dev/null and b/imgs/vscode-marp-preview.png differ diff --git a/imgs/vscode-noconflictbuttons.png b/imgs/vscode-noconflictbuttons.png new file mode 100644 index 0000000..a982981 Binary files /dev/null and b/imgs/vscode-noconflictbuttons.png differ diff --git a/imgs/vscode-settingssync.png b/imgs/vscode-settingssync.png new file mode 100644 index 0000000..5d47611 Binary files /dev/null and b/imgs/vscode-settingssync.png differ diff --git a/imgs/vscode-source-control.png b/imgs/vscode-source-control.png new file mode 100644 index 0000000..9ac90b3 Binary files /dev/null and b/imgs/vscode-source-control.png differ diff --git a/imgs/vscode-tabs.png b/imgs/vscode-tabs.png new file mode 100644 index 0000000..ce52785 Binary files /dev/null and b/imgs/vscode-tabs.png differ diff --git a/imgs/vscode-working-tree.png b/imgs/vscode-working-tree.png new file mode 100644 index 0000000..fc15db0 Binary files /dev/null and b/imgs/vscode-working-tree.png differ diff --git a/using-vscode-slides.html b/using-vscode-slides.html new file mode 100644 index 0000000..f10502c --- /dev/null +++ b/using-vscode-slides.html @@ -0,0 +1,318 @@ +Using VS Code
    +

    Using VS Code

    +
    +
    +

    Project folder as a workspace

    +
      +
    • We'll unlock some important features of VS Code by opening our project folder as a workspace +
        +
      • You can even have workspace-specific settings
        • +
      +
      • +
    • If you are working on multiple projects at once, keep things clear and open dedicated VS code windows for the respective projects!
      • +
    • When you open VS Code from the start menu, it has no workspaces open +
        +
      • To open a folder as a workspace, click Open Folder and navigate to the root folder of your project
        • +
      +
      • +
    • Another way is to not open VS Code from the start menu at all +
        +
      • Instead, right-click the project folder in the Windows file explorer and choose Open with Code
        • +
      +
      • +
    +
    +
    +

    The VS code interface

    +
      +
    • VS code user interface has three important views to consider: +
        +
      • The tabbed side bar (B)
        • +
      • The code editor groups (C)
        • +
      • The terminal panel (D)
        • +
      +
      • +
    +
    +
    + + +
      +
    • Use the buttons (or their respective keyboard shortcuts) in the activity bar to display (and hide!) different views in the side bar
      • +
    +
      +
    1. Explorer (CTRL+SHIFT+E): Display project folder and ints contents
      2. +
    2. Search (CTRL+SHIFT+F): Search your project
      3. +
    3. Source control (CTRL+SHIFT+G): Use Git actions. See more here
      4. +
    4. Run and Debug: Debugging. Not in use in this course
      5. +
    5. Extensions (CTRL+SHIFT+X): Install & manage extensions
      6. +
    +
      +
    • Some extensions add icons that appear under these five.
      • +
    +
    +
    +

    Explorer

    + +
      +
    • In the explorer view, you can +
        +
      • see a list of open editors
        • +
      • and more importantly, access files inside your project folder
        • +
      +
      • +
    +
    +
    +

    Editor groups

    +
      +
    • The opened tabs have two modes: temporary and permanent
      • +
    • The filename of a temporary tab is shown with cursive +
        +
      • If you single-click a file on the explorer view, a file will open as a temp file
        • +
      • There are only one temp file at once: Click another, and it will replace the previous one
        • +
      • Double-click the file or the tab title to make a temporary tab permanent
        • +
      +
      • +
    • You can show editors side-by side by grabbing from the tab title
      • +
    • If changes to a file are not saved, the close button will appear as ⚪ instead of
      • +
    • Tabs with changes are shown in an effect colour
      • +
    +
    +
    +

    +
    +
    +

    Annoying bullshit

    +
      +
    • Some default settings make things harder than they should be
      • +
    • Disable Three-way Merge editor +
        +
      • Preferences > Git: Merge Editor
        • +
      +
      • +
    • Disable autocomplete on certain characters +
        +
      • Preferences > Editor: Accept Suggestion On Commit Character
        • +
      +
      • +
    +
    +
    +

    Using VS code like a pro

    +
      +
    • The key to using VS code effectively is mastering the shortcuts.
      • +
    • This way, you'll minimize your mouse usage and can focus on using your keyboard.
      • +
    +
    +
    +

    VS code shortcuts

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    KeybindingCommandWhen
    CTRL+FFindEditor
    CTRL+SHIFT+FFind in files-
    CTRL+SHIFT+HReplace in files-
    ALT+⬆/⬇Move code line up/downEditor (not read-only)
    CTRL+'Toggle line commentEditor (not read-only)
    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    KeybindingCommandWhen
    CTRL+BView: toggle side bar-
    CTRL+§View: Open instance of the file to the side-
    CTRL+WView: Close editor tab-
    CTRL+SHIFT+POpen command palette-
    CTRL+PGo to file-
    CTRL+ÖView: toggle terminalTerminal is active
    +
    I suggest disabling the CTRL+SHIFT+W shortcut that by default closes VS Code. Easy to trigger by accident!
    +
    +
    +

    Omnisharp shortcuts for C#

    +
      +
    • F2: Rename variable and automatically update references +
        +
      • Naming things correctly on the first go is difficult!
        • +
      +
      • +
    • CTRL+LMB +
        +
      • when clicking a method reference: jump to definition
        • +
      • when clicking the method definition: jump to references
        • +
      +
      • +
    +
    +
    +

    Editing keyboard shortcuts

    +
      +
    • In Preferences > Keyboard Shortcuts, you can add own shortcuts and change existing ones
      • +
    • For example, CTRL+TAB / CTRL+SHIFT+TAB: +
        +
      • Default behaviour is View: Open Next/Previous Recently Used Editor
        • +
      • This opens the tabs in the order of recent use, and it can be confusing
        • +
      • I prefer View: Open Next Editor / View: Open Previous Editor (same as how it works in Chrome!)
        • +
      +
      • +
    • Some shortcuts need an additional When parameter to know when the shortcuts are used +
        +
      • Examples in the next slide
        • +
      +
      • +
    +
    +
    +

    My extra shortcuts (not enabled by default)

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    KeybindingCommandWhen
    CTRL+SHIFT+DCopy line downeditorTextFocus && !editorReadOnly
    CTRL+SHIFT+⬇Move line downeditorTextFocus && !editorReadOnly
    CTRL+SHIFT+⬆Move line upeditorTextFocus && !editorReadOnly
    ALT+F3Select All Occurrences of Find MatcheditorFocus
    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    KeybindingCommandWhen
    CTRL+TABView: Open Next Editor
    CTRL+SHIFT+TABView: Open Previous Editor
    CTRL+ÄView: Focus Active Editor GroupterminalFocus
    CTRL+ÄTerminal: Focus Terminal
    CTRL+SHIFT+ÄView: Toggle Maximized Panel (makes terminal big)
    +
    +
    +

    Extra tip

    +

    In the Search panel, press ⬆ & ⬇ to browse the search history.

    +
    +

    * ***CTRL+.*** auto-import / auto-create missing functions

    \ No newline at end of file diff --git a/using-vscode.md b/using-vscode.md new file mode 100644 index 0000000..3f16ff4 --- /dev/null +++ b/using-vscode.md @@ -0,0 +1,143 @@ +--- +title: Using VS Code +marp: true +paginate: true +math: mathjax +theme: buutti +--- + + + +# Using VS Code + +## Project folder as a workspace + +* We'll unlock some important features of VS Code by opening our project folder as a ***workspace*** + * You can even have workspace-specific settings +* If you are working on multiple projects at once, keep things clear and open dedicated VS code windows for the respective projects! +* When you open VS Code from the start menu, it has no workspaces open + * To open a folder as a workspace, click *Open Folder* and navigate to the root folder of your project +* Another way is to not open VS Code from the start menu at all + * Instead, right-click the project folder in the Windows file explorer and choose *Open with Code* + +## The VS code interface + +* VS code [user interface](https://code.visualstudio.com/docs/getstarted/userinterface) has three important views to consider: + * The tabbed ***side bar*** (B) + * The code ***editor groups*** (C) + * The terminal ***panel*** (D) + +![bg height:70% right:60%](https://code.visualstudio.com/assets/docs/getstarted/userinterface/hero.png) + +## Side bar + +![bg height:80% left:17%](imgs/vscode-tabs.png) + +* Use the buttons (or their respective keyboard shortcuts) in the activity bar to display (and hide!) different views in the side bar +1) Explorer (***CTRL+SHIFT+E***): Display project folder and ints contents +2) Search (***CTRL+SHIFT+F***): Search your project +3) Source control (***CTRL+SHIFT+G***): Use [Git](../project-management/1-git-basics) actions. See more here +4) Run and Debug: Debugging. Not in use in this course +5) Extensions (***CTRL+SHIFT+X***): Install & manage extensions +* Some extensions add icons that appear under these five. + +### Explorer + +![bg height:80% left:30%](imgs/vscode-explorer.png) + +* In the explorer view, you can + * see a list of open editors + * and more importantly, access files inside your project folder + +## Editor groups + +* The opened tabs have two modes: temporary and permanent +* The filename of a temporary tab is shown with *cursive* + * If you single-click a file on the explorer view, a file will open as a temp file + * There are only one temp file at once: Click another, and it will replace the previous one + * Double-click the file or the tab title to make a temporary tab permanent +* You can show editors side-by side by grabbing from the tab title +* If changes to a file are not saved, the close button will appear as ⚪ instead of $\times$ +* Tabs with changes are shown in an effect colour + +--- + +![](imgs/vscode-editor.png) + +## Annoying bullshit + +* Some default settings make things harder than they should be +* Disable Three-way Merge editor + * *Preferences > Git: Merge Editor* +* Disable autocomplete on certain characters + * *Preferences > Editor: Accept Suggestion On Commit Character* + +## Using VS code like a pro + +* The key to using VS code effectively is ***mastering the shortcuts***. +* This way, you'll minimize your mouse usage and can focus on using your ***keyboard***. + +## VS code shortcuts + +| Keybinding | Command | When | +|---------------------------------|------------------------|------------------------| +| ***CTRL+F*** | Find | Editor | +| ***CTRL+SHIFT+F*** | Find in files | - | +| ***CTRL+SHIFT+H*** | Replace in files | - | +| ***ALT+⬆/⬇*** | Move code line up/down | Editor (not read-only) | +| ***CTRL+'*** | Toggle line comment | Editor (not read-only) | + +--- + +| Keybinding | Command | When | +|--------------------|---------------------------------------------|--------------------| +| ***CTRL+B*** | View: toggle side bar | - | +| ***CTRL+§*** | View: Open instance of the file to the side | - | +| ***CTRL+W*** | View: Close editor tab | - | +| ***CTRL+SHIFT+P*** | Open command palette | - | +| ***CTRL+P*** | Go to file | - | +| ***CTRL+Ö*** | View: toggle terminal | Terminal is active | + + + +### Omnisharp shortcuts for C# + + * ***F2***: Rename variable and automatically update references + * Naming things correctly on the first go is difficult! + * ***CTRL+LMB*** + * when clicking a method reference: *jump to definition* + * when clicking the method definition: *jump to references* + + +### Editing keyboard shortcuts + +* In *Preferences > Keyboard Shortcuts*, you can add own shortcuts and change existing ones +* For example, ***CTRL+TAB*** / ***CTRL+SHIFT+TAB***: + * Default behaviour is *View: Open Next/Previous Recently Used Editor* + * This opens the tabs in the order of recent use, and it can be confusing + * I prefer *View: Open Next Editor* / *View: Open Previous Editor* (same as how it works in Chrome!) +* Some shortcuts need an additional `When` parameter to know when the shortcuts are used + * Examples in the next slide + +### My extra shortcuts (not enabled by default) + +| Keybinding | Command | When | +|--------------------|----------------------------------------|--------------------------------------| +| ***CTRL+SHIFT+D*** | *Copy line down* | `editorTextFocus && !editorReadOnly` | +| ***CTRL+SHIFT+⬇*** | *Move line down* | `editorTextFocus && !editorReadOnly` | +| ***CTRL+SHIFT+⬆*** | *Move line up* | `editorTextFocus && !editorReadOnly` | +| ***ALT+F3*** | *Select All Occurrences of Find Match* | `editorFocus` | + +--- + +| Keybinding | Command | When | +|----------------------|-----------------------------------------------------|-----------------| +| ***CTRL+TAB*** | *View: Open Next Editor* | | +| ***CTRL+SHIFT+TAB*** | *View: Open Previous Editor* | | +| ***CTRL+Ä*** | *View: Focus Active Editor Group* | `terminalFocus` | +| ***CTRL+Ä*** | *Terminal: Focus Terminal* | | +| ***CTRL+SHIFT+Ä*** | *View: Toggle Maximized Panel* (makes terminal big) | | + +## Extra tip + +In the Search panel, press ⬆ & ⬇ to browse the search history. \ No newline at end of file diff --git a/vscode-setup-slides.html b/vscode-setup-slides.html new file mode 100644 index 0000000..dd7a612 --- /dev/null +++ b/vscode-setup-slides.html @@ -0,0 +1,98 @@ +VS Code setup
    +

    VS Code setup

    +
    +
    +

    What is Visual Studio Code?

    +
      +
    • VS Code (or just VSC) is a popular open source text editor / IDE (integrated development environment) by Microsoft
      • +
    • Very extensible by extensions
      • +
    • Has many language-specific features like Omnisharp for C#
      • +
    +
    +
    +

    Visual Studio Code is not Visual Studio

    +
      +
    • Visual Studio is an older, bulkier IDE, also by Microsoft +
        +
      • it has more features!
        • +
      +
      • +
    • Visual Studio Code is quite new, relatively lightweight +
        +
      • originally scarce in features
        • +
      • more popular in web development
        • +
      +
      • +
    • Both are used for Unity development
      • +
    • We'll be using VS Code on this course + +
      • +
    +
    +
    +

    VS Code installation

    +
      +
    • During installation, check these two options:
      +
      • +
    +
    +
    +

    Logging into VS Code

    +
      +
    • You can log in with your GitHub account to VS Code in the Accounts tab
      • +
    • Then, by turning on Settings sync, your user-defined settings are carried over to whichever computer you're working on
      +
      • +
    +
    +
    +
      +
    • Open the project folder in VS Code +
        +
      • Either by opening the folder from File Explorer context menu (Open with Code)
        • +
      • Or in VS Code File > Open Folder...
        • +
      +
      • +
    +
    +
    +

    Extra: Other extensions

    + +
      +
    • Marp for VS Code +
        +
      • +

        If you want to read these slides inside VS Code

        +
        • +
      • +

        After installation, open this .md file from the course repository

        +
        • +
      • +

        Click the Open preview to the side button

        +

        +
        • +
      +
      • +
    • GitLens & Git Graph (See Git basics)
      • +
    +
    +
    \ No newline at end of file diff --git a/vscode-setup.md b/vscode-setup.md new file mode 100644 index 0000000..a9eede8 --- /dev/null +++ b/vscode-setup.md @@ -0,0 +1,57 @@ +--- +title: VS Code setup +marp: true +paginate: true +math: mathjax +theme: buutti +--- + + + +# VS Code setup + +## What is Visual Studio Code? + +* VS Code (or just VSC) is a popular open source text editor / IDE (integrated development environment) by Microsoft +* Very ***extensible*** by extensions +* Has many language-specific features like Omnisharp for C# + +## Visual Studio Code is not Visual Studio + + * Visual Studio is an older, bulkier IDE, also by Microsoft + * it has more features! + * Visual Studio Code is quite new, relatively lightweight + * originally scarce in features + * more popular in web development +* Both are used for Unity development +* We'll be using VS Code on this course + * ***Note:*** VS Code Unity Debug Extension [has been recently deprecated](https://github.com/Unity-Technologies/vscode-unity-debug/issues/206) + * We don't need the extension on this course, but it's good to know + +## VS Code installation + +* During installation, check these two options: + ![](imgs/vscode-installation.png) + +## Logging into VS Code + +* You can log in with your GitHub account to VS Code in the ***Accounts*** tab +* Then, by turning on ***Settings sync***, your user-defined settings are carried over to whichever computer you're working on + ![](imgs/vscode-settingssync.png) + +--- + +* Open the project folder in VS Code + * Either by opening the folder from File Explorer context menu (*Open with Code*) + * Or in VS Code *File > Open Folder...* + +## Extra: Other extensions + + +* *Marp for VS Code* + * If you want to read these slides inside VS Code + * After installation, open this .md file from the course repository + * Click the *Open preview to the side* button + + ![](imgs/vscode-marp-preview.png) +* GitLens & Git Graph (See [Git basics](1-git-basics)) \ No newline at end of file