### GDSC NYUST x 資訊創客社 <br> ### 軟體開發工具入門讀書會 #### GitHub 課程 <br> #### 2023/10/25 ( Wed ) 19:00 - 21:00 #### 講師：蘇祐民 #### 本次課程影片： <img src="" height="200px"> --- # GitHub *YoMin Su* --- ## 課程簡介 ---- ### 簡單的說 > 學習使用GitHub提供的各個功能 ---- ### 複雜的說 - 註冊GitHub帳號 - 交換SSH金鑰 - 建立自己的儲存庫 - 拖一份儲存庫或從本地端推送 - 線上檢視、比對、修改程式碼 - 學會使用Issue, PR - 嘗試使用Actions, Projects - 幫版本打Tags - 問題與討論 - 回家練習 --- ## 註冊帳號與金鑰交換 > 連結點我：[GitHub](https://github.com/) ---- ### 先來註冊  按下右上角的『Sign up』 ---- ### 填寫個人資料  請輸入要使用的信箱、密碼、使用者名稱 要記得到信箱收啟用信喔！ ---- ### 登入GitHub  回到首頁後，點選『Sign in』按鈕 輸入剛剛註冊的帳號或密碼 ---- ### Dashboard  登入後，這裡就是你的儀表板(主頁) 接下來，要進行SSH的金鑰交換 ---- ### 進入設定區域 | Step 1 | Step 2 | Step 3 | |:----------------------------------------:|:----------------------------------------:|:----------------------------------------:| |  |  |  | | 點選右上角的人頭 | 在選單中點選『Settings』 | 在左側列表中選擇『SSH and GPG keys』 | ---- ### 新增SSH金鑰  剛剛註冊的使用者，這個列表會是空的 請按下右上角的『New SSH key』 ---- ### 填入必要的資訊  接下來要在電腦端生成非對稱加密的公鑰/私鑰對 並將生成的公鑰填入到畫面上的『Key區塊』中 ---- ### 開啟電腦中的終端機 Windows: ```bash= cmd powershell wt #如果有安裝WindowsTerminal ``` macOS: ```bash= terminal iterm #如果有安裝iTerm ``` ---- ### 生成所需要的鑰匙對 ```bash= ssh-keygen ``` 工具會詢問儲存位置與密碼短語，按下Enter可跳過  ---- ### 印出自己的公鑰資訊 <br/> 如果是用CMD： ```bash= more .ssh\id_rsa.pub ``` 如果是PowerShell或是macOS： ```bash= cat .ssh/id_rsa.pub ```  ---- ### 複製並貼入到網頁中  按下『Add SSH key』後，新增就完成了 > 若使用者名稱是中文，請幫紀錄加上英文的Title，避免新增失敗！ ---- ### 確認鑰匙在列表上  當鑰匙建立後，會在標題列顯示對應的電腦名稱，如果有手動設定標題，會顯示自己填寫的內容，若沒有，請回頭看一下自己複製的內容的最後一段 --- ## 建立自己的儲存庫 ---- ### 回到自己的首頁  點選左側Top Repository旁，綠色的『新增按鈕』 ---- ### 填寫建立儲存庫所需要的資訊  ---- ### 填寫建立儲存庫所需要的資訊(2)  ---- ### 儲存庫資訊說明 | 項目 | 說明 | | ----------------- | -------------- | | Repository name | 儲存庫名稱 | | Description | 儲存庫說明 | | Public / Private | 是否開源 | | Add a README file | 是否加入讀我檔 | | Add .gitignore | 是否排除特定檔案 | | Choose a license | 選擇專案的授權條款 | ---- ### 建立好的空儲存庫  --- ## 從本地端設定Remote並推送 ---- ### 回到本地端的專案資料夾中  ---- ### 新增一些範例內容並Commit內容  ```shell= git add . git commit ``` ---- ### 設定遠端位置  ```shell= git remote add origin <repo url> ``` ---- ### 推送本地端內容到GitHub  ```shell= git push origin main ``` ---- ### 回到GitHub上確認內容  --- ## 透過GitHub ## 線上檢視、比對、編輯程式碼 ---- ### 檢視程式碼 | Step 1 | Step 2 | | ---------------------------------------- | ---------------------------------------- | |  |  | | 在儲存庫中點選想檢視的檔案 | 程式碼將直接顯示在網頁中，也可以切換到Blame模式，檢視每一行被記錄下來的時間 | ---- ### 比對程式碼 為了能顯示出版本之間的差異，開個新的分支，增加檔案內容，並做紀錄  ```shell= git branch <new branch name> git switch <branch name> ``` ---- ### 比對程式碼(2) 將新分支的內容推送到GitHub上  ```shell= git push origin <new branch name> ``` ---- ### 比對程式碼(3) 重新整理網頁，確認推送的分支已經顯示在網頁中  ---- ### 比對程式碼(4) 在當下儲存庫的網址列中，加上『/compare』  ---- ### 比對程式碼(5)  ---- ### 線上編輯程式碼 在任何一個你想繼續修改的分支上，按下鍵盤上的『．』  ---- ### 線上編輯程式碼(2) 這時會開啟網頁版的VSCode，並帶入選擇的分支，也就可以進行程式碼的修改與儲存！  ---- ### 線上編輯程式碼(3) 這時再回到GitHub網頁查看剛剛儲存的Commit，會發現修改好的內容會直接紀錄在儲存庫中！  ---- ### 線上編輯程式碼(4) 進入到Commit紀錄中查看，會發現透過GitHub線上儲存的Commit，會包含<span class="lightgreen">Verified</span>字樣，表示經過簽章  --- ## Issue ---- ### 什麼是Issue？ - 問題回報區 - 新功能請求區 - 問題詢問區 - etc... > 根據用法的不同，可以有各種作用 ---- ### 該如何開新的Issue？ 請先點選網頁中的Issues分頁，接著點擊右邊的『New issue』，接著就可以開始撰寫Issue內容  ---- ### 撰寫Issue內容  ---- ### Issue項目說明 | 項目 | 說明 | | --------- | ----------------------------------- | | Title | Issue 標題 | | 編輯區 | 撰寫Issue內容，可以使用Markdown語法 | | Assignees | 參與這個Issue討論的開發者 | | Labels | 幫Issue標記分類 | | Projects | 這個Issue與GitHub Project的關聯 | | Milestone | 這個Issue與里程碑的關聯 | ---- ### 來寫個Issue範例  內容寫好後，就可以按下『Submit new issue』 ---- ### 回到Issue分頁  可以注意到『Open』狀態的Issue有一個，正是剛剛建立的紀錄 ---- ### 點入Issue看一看  ---- ### 修改程式碼來解決Issue > 可以注意到Commit訊息上的『#1』  ---- ### 回過頭來看Issue網頁  ---- ### 準備來關閉Issue  確認沒有問題後， 就可以按下『Close with comment』 （若沒有留言，會顯示為『Close issue』） ---- ### Issue關閉後  ---- ### 看看Issue列表  ---- ### 如果你希望設計Issue的範本 請到儲存庫的『Settings』中，找到『Features』區塊，就可以在這裡設定範本了！  ---- ### Issue範本 有『Bug report』、『Feature request』與『Custom』可以選，數量也能根據需要增加！  --- ## Pull Request ### (Merge Request) ---- ### 什麼是Pull Request？ > 一個合併程式碼的過程 可以是： - 從別人Fork出去的內容合併回原本專案 - 從專案中其他分支合併回主分支 ---- ### 先回到main分支加入一些新的內容  ---- ### 該如何開啟新的PR呢？ 請回到GitHub網頁，點選『Pull Request』分頁，接著點擊右邊的『New pull request』按鈕  ---- ### 比對修改 請讓base保留為主幹、compare修改為要合併回去的分支，按下右邊的『Create pull request』  > 無法自動合併是正常的，毋須擔心 ---- ### 撰寫PR訊息  填寫完成後，就可以按下『Create pull request』 ---- ### 看一看PR的內容  ---- ### 看一看PR的內容(2)  ---- ### 可以如何解決衝突？ 可以直接點選畫面中的『Resolve conflicts』，這將會開啟線上合併工具  ---- ### 合併衝突  > 處理前 ---- ### 合併衝突  > 處理後 ---- ### 修改完成時 請先按下右上角的『Mark as resolved』，接著就可以點擊『Commit merge』了！  ---- ### 再次來看PR資訊  ---- ### 進行合併！ 請直接按下剛剛看到的『Merge pull request』，接著就可以撰寫這次合併的Commit內容，完成後請點選『Confirm merge』  ---- ### 搞定！  ---- ### 補充說明 此時，你應該會看到介面上的顏色變成<span class=purple>紫色</span>，並且左上角顯示『Merged』，這樣一來就合併完成了，是否刪除cmp分支，可以自由決定，可以點選『Delete branch』移除該分支，若你反悔了，想復原合併，也可以按下『Revert』按鈕～  --- ## Actions ---- ### 什麼是Actions？ > 自動化的必備工具 可以怎麼用： - 專案建置測試 - 執行Docker映像打包 - 部署到目標機器 - 專案覆蓋率測試 - etc... ---- ### 該怎麼起頭？ 先切換到Actions分頁，讓我們選擇其中一項範本來修改  ---- ### 選擇哪個？ 因為我們是Python專案，希望執行基本的測試，因此，選擇中間下面的選項  ---- ### 確認內容  若沒有想要修改的部分，可以直接點選右上角的『Commit changes』 ---- ### 撰寫Commit資訊  ---- ### 回頭看看Actions分頁 因為我們剛剛是直接對main分支進行修改，因此剛好觸發了Actions進行測試，結果顯示為『失敗』  ---- ### 為專案加入測試檔案 回到線上編輯工具中，建立一個『tests』資料夾，並建立以『test_』為開頭的測試檔  ---- ### 加上Pytest的設定檔 由於未指定專案路徑會讓Pytest不知道要到哪裡找到我們自己寫的方法，因此要加入『pytest.ini』讓工具正常工作  ---- ### 回到Actions列表 可以看到我們在加入正確的設定檔後，Pytest的檢查就通過了，也因此，最新一筆顯示為『<span class=actiongreen>正常</span>』  ---- ### 點入Action細節 會顯示剛剛新增的python-app.yml中定義好的Jobs，也就是圖片中的build  ---- ### 點入Jobs中查看 這裡可以看到實際上Actions執行了Jobs中的每一個步驟，若出現錯誤，也會呈現在這裡，會在錯誤項上顯示『』  ---- ### Actions實際上會用於哪裡？ - CI (Continuous integration) - CD (Continuous deployment) - 程式碼測試、檢查 (Unit Test, Integration test, Coverage Test) - 程式碼安全性測試 (SonarQube, etc...) --- ## Projects ---- ### 什麼是Projects？ > 專案分工與追蹤進度的輔助工具 有名的替代方案：Trello ---- ### 該怎麼開始？ 首先一樣要切換到Projects的分頁中，點開『Link a project』旁的下拉選單，選擇『New project』  ---- ### 選擇第一個View要使用的模式 可以根據需要去進行挑選，這裡將選擇預設的『Table』，接著按下『Create』  ---- ### 加入內容 在這裏，可以將儲存庫中的Issue或是PR跟Project關聯起來  ---- ### 建立自訂欄位 除了畫面上的內容之外，同樣也可以建立自己的欄位，以滿足不同的需求  ---- ### 範例欄位：優先級 建立名為『Priority』的欄位，並加入『High』、『Medium』、『Low』三個選項，使用的類型是『Single select』  ---- ### 補充說明 Projects除了列點與分配外，同樣也可以基於時間線去安排工作進度與各個項目的處理狀況，讓專案能維持在進度安排上。對於工程師來說，只要去看每週被安排到的TODO項目，就可以知道需要做的功能有哪些，哪些需求尚未被處理，哪些錯誤等待維修，減少重工與資訊搜集的時間！ --- ## Tags ---- ### 什麼是Tags？ > 當設計好的程式碼適合作為一個版本發佈時，幫它打上的標記 ---- ### 該怎麼打上標記 可以用以下的指令做到： ```shell= git tag <tag name> ``` 能針對『目前』的Commit加上Tag標記 ---- ### 若我想對之前的Commit加上Tag的話？ 可以先透過git log檢視之前的紀錄： ```shell= git log --oneline ```  ---- 再對想加上Tag的Commit輸入： ```shell= git tag <tag name> <commit hash> ``` 再重新看一下Log的紀錄：  ---- ### 如何推送Tag到Remote？ 可以使用以下的指令： ```shell= git push origin --tags ```  ---- ### 回到GitHub看一看 在『Code』分頁的右側，有個『Release』區塊，可以看到  ---- ### 點進去看一下 會得到更詳細的版本資訊  ---- ### Tags的用途？ 當你的專案有大量的程式碼在裡面時，總會需要對幾個比較重要的版本加上標記，這時就能透過Tag做到，除此之外，GitHub也可以保護特定的Tag只能由幾個特定的開發人員進行標記，必免發生誤用的狀況。 而當有了Tags後，就可以從Tags去建立專案希望發佈的Release，也就是平時在開源專案下常看到可以下載檔案的版本！ --- ## Q & A ### 有沒有什麼想要詢問的內容呢？ --- ## 回家作業 > TBD --- ## 感謝各位  <style> .lightgreen { color: #3FB950; } .actiongreen { color: #00BC3F; } .purple { color: #9154ED; } </style>