Working with Git, Python and Virtual Environment on VS Code

Before we start

在这篇文章中我会假定读者会对于Git和Github对于有一定的了解，并成功安装了VS Code。Git是一个版本控制软件，简单点说就是用户可以通过Git将本地代码变动上传至云端代码托管平台（如GitHub），同时Git也会记录每次代码提交的细节，从而使用户能够追踪开发过程中代码的变动，也能够灵活将本地代码回滚到某一次提交的内容。如果你想了解更多有关Git的内容，也可以参考这篇博客进行进一步了解。

Check git installation on your laptop

你可以通过在终端（Terminal）中输入以下命令检查你的电脑是否已经安装 Git :


git --version

如果你的电脑已经安装了 Git，你将会在终端内得到类似的输出信息：


git version 2.37.0 (Apple Git-136)

如果你收到了包含以下内容的报错信息，则说明电脑内没有安装python：


command not found: git

你可以通过参考这篇文章下载 Git。

Using git for obtaining the exercises

在获取课程 exercises repository （包含课程代码联系的代码仓库）之前，你需要通过 Github Classroom 接受课程（注意：接受课程前你需要通过邮件联系 course instructor Professor Colin Cotter 并告知他你的 imperial short code，同时在接受课程时选择你的short code。如果你忽略了前一步你的short code将不会出现在页面上，请直接联系教授，不要选择 Can't find your name），这样才能让 Maths Department 在批改代码时将你的代码和你的short code联系在一起）。

成功获取exercises repository之后，点击页面右上角的Github Logo（一只黑猫）进入你的Home Page，在左侧菜单栏 Recent Repositories 中你会看到你的课程exercises repository （格式为 Imperial-MATHxxxxx/clacourse-2022-<your-github-username>，在这里我以我本人在2021年获取的code repository为例），你可以通过点击该链接进入 repository。

Important! Set up your SSH Key

在进入exercise repository之前我们还需要进行另一项设置 - 设置 SSH Key。简单点来说SSH是一种安全访问远程资源（如你 Github 上的 repository）的方式，我们可以在 Github 账户中添加你的电脑的SSH Key，从而保证你获取/提交代码的操作是安全的，而且在每次操作时不必输入你的安全信息（如用户名、密码等）。虽然保证获取/提交代码的安全性的方式有很多，但我个人认为 SSH 是最容易配置的一种方式，所以在本文中只介绍这一种方式。

你需要进入 Terminal 输入以下命令生成SSH Key：


ssh-keygen

如果成功生成SSH Key，你会看到类似的终端输出（当终端询问 filepath/passphrase 时，你可以通过敲击回车选择默认值继续下一步）


Generating public/private rsa key pair.
Enter file in which to save the key (/Users/frankfan/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/frankfan/.ssh/id_rsa
Your public key has been saved in /Users/frankfan/.ssh/id_rsa.pub
The key fingerprint is:
SHA256:N******************k your-user-name-on-machine@********
The key's randomart image is:
+---[RSA 3072]----+
| some dots ...   |
+----[SHA256]-----+

获取生成的SSH Key：


cat ~/.ssh/id_rsa.pub
# Expected output (some parts are hidden)
ssh-rsa AAAAB3NzaC1yc2*************+Un++ZxU3rN0/GvoLe0s0= f*****n@3c******c

复制输出的 SSH Key 到剪贴板，打开 GitHub 页面，点击页面右上角头像，在下拉菜单栏内选择 Settings 进入设置界面。通过选择设置界面左侧边栏的 SSH and GPG Keys 以及页面中蓝色的 New SSH Key 添加本机的SSH Key，添加 SSH Key 的界面如下图：

将复制到剪贴板的本机SSH Key粘贴到页面中 Key 下方的文本框中，同时设置好页面中 Title 的值，点击 Add SSH Key 即可添加新的 SSH Key （添加成功后 SSH/GPG Keys 页面新增内容如下）：

完成添加后我们就可以进入 exercise repository 获取代码到本地了。

进入 exercises repository 后，点击页面内的 Code 按钮，选择 SSH 并点击剪贴板按钮复制 repository URL （你需要用到这个URL获取你的exercises）。

你需要在 Terminal 中输入以下命令来获取 exercises 并保存文件夹到桌面 (你当然可以保存到你喜欢的任意文件夹，这里给出 MacOS 下保存到桌面的命令，其他系统的命令会有所改动，更多细节请参考这里)：


# Go to Desktop in terminal
cd ~/Desktop
# clone the repository, and rename it as comp-lin-alg-course
git clone <your-url-to-repository> comp-lin-alg-course

到此为止你可以关闭终端 app，后续的终端操作会在VS Code内部进行。

Start editing your code in Visual Studio Code

打开VS Code 并点击 `Open` 选择课程 exercises 的文件夹 comp-lin-alg-course, 具体界面如下：

选择课程 exercises 文件夹 `comp-lin-alg-course`

进入 comp-lin-alg-course 文件夹后，我们需要进行：

编辑器设置

为了让你有一个更好的 VS Code 使用体验，我推荐你下载 VS Code 中的 Python 插件, 具体下载界面如下图所示：

同时我推荐设置 代码自动保存 功能。通过快捷键 ⌘ + , (MacOS系统) 或 ctrl + , （Windows/Linux 系统）弹出设置界面，在 Files: Auto Save 中点击下拉框选择 afterDelay 即可开启自动保存功能。

虚拟环境设置

通过顶部菜单栏 Terminal > New Terminal 在 VS Code 内部打开终端，在终端中输入以下命令创建虚拟环境并安装环境依赖（numpy, scipy, pytest, matplotlib等第三方库）


# Using pre-set script to create virtual environment "claenv"
./scripts/cla_install_venv claenv

安装完成后即可在 VS Code 中设置文件夹内部的默认虚拟环境，根据下图提示设置 claenv 为默认 Python 环境：

设置完成后，页面底部的Python 环境会从原先的系统 Python 切换为

<python3-version> ('claenv': venv) 。同时在 VS Code 中打开一个新的 Terminal 后，VS Code 会通过以下终端命令自动将 Python环境切换至你的虚拟环境：


# This is done by VS Code, you don't need to anything
source /<your-path-to-comp-lin-alg-course>/claenv/bin/activate

为了验证是否你的终端 Python 环境为虚拟环境，你可以输入以下命令进行检查：


which python
# This is the expected output of your venv path
/your-path-to-comp-lin-alg-course/claenv/bin/python

完成设置后我们就可以开始写代码了。在完成练习中我有两点需要强调，分别是：

测试实现的代码

在这门课中我们使用 pytest 对于代码进行测试，测试的一般命令为：


# Test all functions implemented
pytest test/
# Test functions implemented in exercise X
pytest test/test_exercisesX.py

你的测试结果将会看起来像这样：


platform darwin -- Python 3.9.14, pytest-7.1.2, pluggy-1.0.0
rootdir: /your-path-to-comp-lin-alg-course/
collected 16 items

test/test_exercises1.py ................                               [100%]

如果你想检查测试文件 test_exerciseX.py 中每一个测试用例的正确性，你可以将上面的命令稍作修改：


# Test functions implemented in exercise X and seach test cases
pytest -v test/test_exercisesX.py

你的测试结果将会看起来像这样：


platform darwin -- Python 3.9.14, pytest-7.1.2, ...
cachedir: .pytest_cache
rootdir: /your-path-to-comp-lin-alg-course/
collected 16 items

test/test_exercises1.py::test_basic_matvec[20-20] PASSED              [  6%]
test/test_exercises1.py::test_basic_matvec[40-20] PASSED              [ 12%]
test/test_exercises1.py::test_basic_matvec[20-45] PASSED              [ 18%]
... (hidden cases)
test/test_exercises1.py::test_ABiC[3] PASSED                          [ 81%]
test/test_exercises1.py::test_ABiC[7] PASSED                          [ 87%]
test/test_exercises1.py::test_ABiC[20] PASSED                         [ 93%]
test/test_exercises1.py::test_ABiC[43] PASSED                         [100%]

如果你只想测试某个exercise中的某个函数，如 exercise 1 中的 basic_matvec，你需要找到对应 test file test_exercise1.py 中测试 basic_matvec 的函数/测试用例（通常为 test + exercise中的函数名，例如本文这种情况下为 test_basic_matvec )，使用以下命令对于单个测试用例进行测试：


pytest test/test_exercises1.py::test_basic_matvec

提交你实现的代码

当你完成了函数的实现后，你需要提交你的代码到 Github 让 GTA 进行评分。课程网站上对于提交的相关操作有详细说明，具体是通过 git push 等相关的终端命令来进行提交。我个人认为这对于一些初学者并不是很友好，于是我在这里提出另一种办法：

例如说你已经对于你的 code 做了一些改动，就像这样（VS Code 会在文件内改动的地方进行提示）：

同时 VS Code 的侧栏也会提示你在什么文件发生了改动：

假设我们想要提交的代码变动在 exercises1.py 和 exercises2.py ，我们就可以将鼠标悬于对应条目上方并点击 ➕ 号按钮，将改动添加到 Staged Changes 。

添加改动完成之后，我们需要对于改动进行说明（例如在这个改动中我实现了什么函数，修改了代码风格等等，总体来说应该是一句简要且完整的话，我们叫它 commit message）。你需要把你的说明写在 Message 框中，然后点击 commit 完成改动。

注意：虽然有时候想/写 commit message 会显得多此一举或是令人头疼，但是这对于你回看代码变动或是debug时有很大的帮助，所以请不要因为偷懒而总是写 “first commit”, ”second commit”, ”1”, ”2”, ”3” 等没有什么实际意义的 commit message。同时，一个好的习惯是时常提交代码改动，这也对于你的代码编写也很有帮助。

最后我们需要把完成的改动推送至远端的 GitHub ，我们只需来到编辑器的左下角，点击上传/下载按钮（如下图）即可将改动推送到 GitHub。

你可以通过进入GitHub 上 exercises repository 的界面来检查是否成功上传改动：

我们可以看到 GitHub 上最新的改动来自于八分钟前，同时 commit message 也和我所上传的 message 相同，这说明我们的改动已经上传成功了。

点击上图所描述的页面中的 “138 commits”，你可以追踪你的改动历史记录，如下图：

每条改动记录都会跟随着一串id，你可以把它想象成你的文件在某一个版本下的unique identifier，它也被称为 commit hash（或者commit SHA）。注意：每次coursework你都会被要求上传你的 commit hash，你只需要点击你最新一次 commit hash 左边的按钮就可以复制你的 full commit hash 进行提交，如果不知道那是什么，或者永远不提交，你可能永远看不到你每次coursework coding part的分数是多少了。

感谢你读到了最后，这就是 Computational Linear Algebra 这门课在前期设置需要注意的大致要点了，希望这篇文章对你有用。