GitLab episode almost complete; added more on CleanCode tools

episodes/clean-code.Rmd

@@ -850,7 +850,7 @@ pip install pylint
 
 :::::::::::::::::::::::::::::::::::::::::  callout
 
-##### Running Pyling on a sample program
+##### Running Pylint on a sample program
 
 ```python
 # bad_pylint.py
@@ -972,9 +972,25 @@ Your code has been rated at 10.00/10 (previous run: 5.91/10, +4.09)
 
 ### PyCharm and Clean Code
 
-- Introduce PyCharm, show how to setup a Python interpreter for a project
-- Show how PyCharm is highlighting parts of the code that do not follow coding conventions
-- Show how PyCharm can help with re-factoring - e.g. changing a variable/function name
+Using a modern development environment, such as PyCharm, can greatly facilitate
+writing clean code. In this section we will go over a few ways this can be accomplished.
+
+:::::::::::::::::::::::::::::::::::::::::  callout
+
+##### Configuring a Python interpreter for a PyCharm project
+
+For a given PyCharm project it is possible to setup a python interpreter,
+as shown below:
+
+![](fig/pycharm_python_interpreter.jpg){alt='Running Pytest from PyCharm'}
+
+The selected interpreter can be the system-wide one, or one selected from a
+virtual environment. Once a Python interpreter has been configured, PyCharm
+will use it to run code (e.g. `.py` files part of that project), or analyze
+the code and provide useful hints to the developer.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
 
 ### Unit Tests and Test Coverage
 

episodes/gitlab.Rmd

@@ -252,6 +252,321 @@ work with it throughout this lesson.**
 At the bottom of the page is also a section for deleting a project, in case you
 ever think that is the right thing to do.
 
+
+## Connecting GitLab Projects with Local Git Repositories
+
+Remember from an earlier lesson that we have created a local Git repository
+that looked like this:
+
+![](fig/git-staging-area.svg){alt='Local repository with staging area'}
+
+Now we want to have a GitLab project that will be coupled with this local Git repo.
+The first step here is to follow the steps described in the previous section,
+and create a new GitLab project called 'recipes'. Initially the Git repo for
+this GitLab project will be empty, as shown in the diagram below:
+
+![](fig/git-freshly-made-gitlab-repo.svg){alt='The local and remote Git repos'}
+
+### Connecting the local to remote repository
+
+Now we connect the two repositories.  We do this by making the
+GitHub repository a [remote](../learners/reference.md#remote) for the local repository.
+Go to the home page of the repository on GitLab, click on the blue `Code` button,
+and copy the string below the `Clone with SSH`
+
+![](fig/gitlab_ssh_repo.jpg){alt='Accessing a GitLab repo via SSH'}
+
+:::::::::::::::::::::::::::::::::::::::::  callout
+
+## HTTPS vs. SSH
+
+We use SSH here because, while it requires some additional configuration, it is a
+security protocol widely used by many applications.  The steps below describe SSH at a
+minimum level for GitLab.
+
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+With the `Clone with SSH` string you copied from the GitLab page, go into the local
+`recipes` repository, and run this command:
+
+```bash
+$ git remote add origin [email protected]:alflin/recipes.git
+```
+
+Make sure to use the URL for your repository rather than Alfredo's: the only
+difference should be your username instead of `alflin`.
+
+`origin` is a local name used to refer to the remote repository. It could be called
+anything, but `origin` is a convention that is often used by default in git
+and GitHub, so it's helpful to stick with this unless there's a reason not to.
+
+We can check that the command has worked by running `git remote -v`:
+
+```bash
+$ git remote -v
+```
+
+```output
+origin   [email protected]:alflin/recipes.git (fetch)
+origin   [email protected]:alflin/recipes.git (push)
+```
+
+### SSH Background and Setup
+
+Before Alfredo can connect to a remote repository, he needs to set up a way for his computer
+to authenticate with GitLab so it knows it's him trying to connect to his remote repository.
+
+We are going to set up the method that is commonly used by many different services to authenticate
+access on the command line. This method is called Secure Shell Protocol (SSH). SSH is a cryptographic
+network protocol that allows secure communication between computers using an otherwise insecure
+network.
+
+SSH uses what is called a key pair. This is two keys that work together to validate access. One key
+is publicly known and called the public key, and the other key called the private key is kept private.
+Very descriptive names.
+
+You can think of the public key as a padlock, and only you have the key (the private key) to open it.
+You use the public key where you want a secure method of communication, such as your GitHub account.
+You give this padlock, or public key, to GitLab and say "lock the communications to my account with
+this so that only computers that have my private key can unlock communications and send git commands
+as my GitHub account."
+
+What we will do now is the minimum required to set up the SSH keys and add the public key to a GitLab
+account.
+
+The first thing we are going to do is check if this has already been done on the computer you're on.
+Because generally speaking, this setup only needs to happen once and then you can forget about it.
+
+:::::::::::::::::::::::::::::::::::::::::  callout
+
+##### Keeping your keys secure
+
+You shouldn't really forget about your SSH keys, since they keep your account secure. It's good
+practice to audit your secure shell keys every so often. Especially if you are using multiple
+computers to access your account.
+
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+We will run the list command to check what key pairs already exist on your computer.
+
+```bash
+$ ls -al ~/.ssh
+```
+
+Your output is going to look a little different depending on whether or not SSH has ever been
+set up on the computer you are using.
+
+Alfredo has not set up SSH on his computer, so his output is
+
+```output
+ls: cannot access '/c/Users/Alfredo/.ssh': No such file or directory
+```
+
+If SSH has been set up on the computer you're using, the public and private key pairs will be listed.
+The file names are either `id_ed25519`/`id_ed25519.pub` or `id_rsa`/`id_rsa.pub` depending on how the
+key pairs were set up. Since they don't exist on Alfredo's computer, he uses this command to create them.
+
+##### Create an SSH key pair
+
+To create an SSH key pair Alfredo uses this command, where the `-t` option specifies which type of
+algorithm to use and `-C` attaches a comment to the key (here, Alfredo's email):
+
+```bash
+$ ssh-keygen -t ed25519 -C "[email protected]"
+```
+
+If you are using a legacy system that doesn't support the Ed25519 algorithm, use:
+`$ ssh-keygen -t rsa -b 4096 -C "[email protected]"`
+
+```output
+Generating public/private ed25519 key pair.
+Enter file in which to save the key (/c/Users/Alfredo/.ssh/id_ed25519):
+```
+
+We want to use the default file, so just press <kbd>Enter</kbd>.
+
+```output
+Created directory '/c/Users/Alfredo/.ssh'.
+Enter passphrase (empty for no passphrase):
+```
+
+Now, it is prompting Alfredo for a passphrase. Since he is using his kitchen's laptop that other
+people sometimes have access to, he wants to create a passphrase. Be sure to use something memorable
+or save your passphrase somewhere, as there is no "reset my password" option.
+Note that, when typing a passphrase on a terminal, there won't be any visual feedback of your typing.
+This is normal: your passphrase will be recorded even if you see nothing changing on your screen.
+
+```output
+Enter same passphrase again:
+```
+
+After entering the same passphrase a second time, we receive the confirmation
+
+```output
+Your identification has been saved in /c/Users/Alfredo/.ssh/id_ed25519
+Your public key has been saved in /c/Users/Alfredo/.ssh/id_ed25519.pub
+The key fingerprint is:
+SHA256:SMSPIStNyA00KPxuYu94KpZgRAYjgt9g4BA4kFy3g1o [email protected]
+The key's randomart image is:
++--[ED25519 256]--+
+|^B== o.          |
+|%*=.*.+          |
+|+=.E =.+         |
+| .=.+.o..        |
+|....  . S        |
+|.+ o             |
+|+ =              |
+|.o.o             |
+|oo+.             |
++----[SHA256]-----+
+```
+
+The "identification" is actually the private key. You should never share it. The public key is
+appropriately named.  The "key fingerprint" is a shorter version of a public key.
+
+Now that we have generated the SSH keys, we will find the SSH files when we check.
+
+```bash
+ls -al ~/.ssh
+```
+
+```output
+drwxr-xr-x 1 Alfredo   197121   0 Jul 16 14:48 ./
+drwxr-xr-x 1 Alfredo   197121   0 Jul 16 14:48 ../
+-rw-r--r-- 1 Alfredo   197121 419 Jul 16 14:48 id_ed25519
+-rw-r--r-- 1 Alfredo   197121 106 Jul 16 14:48 id_ed25519.pub
+```
+
+
+##### Copy the public key to GitHub
+
+Now we have a SSH key pair and we can run this command to check if GitHub can read our authentication.
+
+```bash
+ssh -T [email protected]
+```
+
+```output
+The authenticity of host 'gitlab.tudelft.nl (192.30.255.112)' can't be established.
+RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
+This key is not known by any other names
+Are you sure you want to continue connecting (yes/no/[fingerprint])? y
+Please type 'yes', 'no' or the fingerprint: yes
+Warning: Permanently added 'gitlab.tudelft.nl' (RSA) to the list of known hosts.
+[email protected]: Permission denied (publickey).
+```
+
+Right, we forgot that we need to give GitLab our public key!
+
+First, we need to copy the public key.  Be sure to include the `.pub` at the end,
+otherwise you're looking at the private key.
+
+```bash
+cat ~/.ssh/id_ed25519.pub
+```
+
+```output
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDmRA3d51X0uu9wXek559gfn6UFNF69yZjChyBIU2qKI [email protected]
+```
+
+Now, going to the GitLab page in your browser, click on your profile icon in the top right corner
+of the left panel, then click on the `SSH Keys` link under `User Settings` in the same panel:
+
+![](fig/gitlab_ssh_keys.jpg){alt='The SSH Keys page in GitLab'}
+
+Click on the `Add new key` button, which will take you to a page like this:
+
+![](fig/gitlab_add_new_key.jpg){alt='Adding a new key in GitLab'}
+
+Here, you can paste your public key in the `Key` box, add a title, and set an expiration
+date. Once everything is filled in, you can click the `Add key` button.
+
+Now that we've set that up, let's check our authentication again from the command line.
+
+```bash
+$ ssh -T [email protected]
+```
+
+```output
+Welcome to GitLab, @alflin!
+```
+
+Good! This output confirms that the SSH key works as intended. We are now ready to push our
+work to the remote repository.
+
+### Push local changes to a remote
+
+Now that authentication is setup, we can return to the remote.  This command will push the changes from
+our local repository to the repository on GitHub:
+
+```bash
+$ git push origin main
+```
+
+Since Alfredo set up a passphrase, it will prompt him for it. If you completed advanced settings
+for your authentication, it will not prompt for a passphrase.
+
+```output
+Enumerating objects: 16, done.
+Counting objects: 100% (16/16), done.
+Delta compression using up to 8 threads.
+Compressing objects: 100% (11/11), done.
+Writing objects: 100% (16/16), 1.45 KiB | 372.00 KiB/s, done.
+Total 16 (delta 2), reused 0 (delta 0)
+remote: Resolving deltas: 100% (2/2), done.
+To https://gitlab.tudelft.nl/alflin/recipes.git
+ * [new branch]      main -> main
+```
+
+:::::::::::::::::::::::::::::::::::::::::  callout
+
+## Password Managers
+
+If your operating system has a password manager configured, `git push` will
+try to use it when it needs your username and password.  For example, this
+is the default behavior for Git Bash on Windows. If you want to type your
+username and password at the terminal instead of using a password manager,
+type:
+
+```bash
+$ unset SSH_ASKPASS
+```
+
+in the terminal, before you run `git push`.  Despite the name, [Git uses
+`SSH_ASKPASS` for all credential
+entry](https://git-scm.com/docs/gitcredentials#_requesting_credentials), so
+you may want to unset `SSH_ASKPASS` whether you are using Git via SSH or
+https.
+
+You may also want to add `unset SSH_ASKPASS` at the end of your `~/.bashrc`
+to make Git default to using the terminal for usernames and passwords.
+
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+Our local and remote repositories are now in this state:
+
+![](fig/github-repo-after-first-push.svg){alt='GitLab repo after first push'}
+
+We can pull changes from the remote repository to the local one as well:
+
+```bash
+$ git pull origin main
+```
+
+```output
+From https://gitlab.tudelft.nl/alflin/recipes
+ * branch            main     -> FETCH_HEAD
+Already up-to-date.
+```
+
+Pulling has no effect in this case because the two repositories are already
+synchronized.  If someone else had pushed some changes to the repository on
+GitHub, though, this command would download them to our local repository.
+
+
 ## Adding Project Members
 
 So far, each of you has created a GitLab project that no one but you can