GitHub on 弦而時習之

AI 輔助開發 - Copilot 與文件和註解

contact@aotoki.me (蒼時弦也) — Wed, 30 Aug 2023 00:00:00 +0800

最近因為公司有提供 GitHub Copilot 給我們當作工具，我也就順勢將 Copilot 在 Vim 中啟用。這幾個月體驗上跟當初釋出試用版相比，反應速度雖然有提升然而仍然沒有比自己思考的速度還快，但也有改變了開發習慣。

不寫註解

一直以來我都是「不寫註解」的類型，在 Ruby 的語法特性下，只要願意花時間思考命名，大多能很好的表達語意（Semantic）即使在其他類型的語言也能有不錯的效果。

然而，有一些朋友在 Copilot 的應用方式，則會採取「撰寫註解」作為提示（Prompt）來讓 AI 可以幫助他們生成近似預期的程式碼。就這點而言，我是不太認同的，一方面是殘留跟實作重複的說明，另一方面我們仍該追求容易理解、閱讀的程式碼。

以最近在做的 OPass Serverless 專案作為例子，以下是在沒有註解的狀況下讓 AI 輔助生成的，仍然很容易閱讀。

 1export class AttendeeAccess {
// ...
async getScenarios(token: string): Promise<AttendeeScenario> {
const attendee = await this.attendeeRepository.findByToken(token)
if (!attendee) {
return {}
}
 8
const ruleset = await this.rulesetRepository.findByEventId(attendee.eventId, attendee.role)
if (!ruleset) {
return {}
}
13
await runRuleset(attendee, ruleset)
15
return buildAttendeeScenario(ruleset.visibleScenarios)
}
18}

我認為，當我們程式碼中的脈絡（Context）足夠完善時，對 AI 來說是不需要依賴註解去了解意圖，而是能順著工程師的思考分段的推測出所需的內容。

因為還是有出錯的可能性，在生成後還是要回頭檢查，這件事情可以讓「測試」這件事情來輔助，因此寫測試也可能是 AI 時代的重要技巧。

型別文件

型別議題一直以來在軟體開發中都是一種很難下定論的問題，單從 AI 輔助開發的角度來看，我認為他是一種很好的文件，因此像是 TypeScript、Ruby 的 RBS 這類方式，從這個角度來看是個不錯的設計。

接續上一段的實作，我們要將一個實體（Entity）轉換成 UseCase（使用案例）的回傳，來確保 Presentation Layer（表現層）不會對 Domain Layer（領域層）有過多的認知，假設在沒有型別輔助的狀況下，對 AI 來說要判斷這段程式碼如何產生是會有點吃力的。

 1function buildAttendeeScenario(scenarios: Record<string, Scenario>): Record<string, ScenarioInfo> {
let result: Record<string, ScenarioInfo> = {}
 3
for (const scenarioId in scenarios) {
const scenario = scenarios[scenarioId]
result[scenarioId] = {
order: scenario.order,
availableTime: scenario.availableTime,
displayText: scenario.displayText,
usedAt: scenario.usedAt,
locked: scenario.isLocked,
lockReason: scenario.lockReason,
metadata: scenario.metadata,
}
}
16
return result
18}

我們希望將 Scenario 這個實體中的資訊，拆解出來變成 ScenarioInfo 這個 Data Transfer Object（DTO）來回傳，在 TypeScript 中用 { ... } 的情境可能是任意的內容，然而在型別的輔助下，AI 就相對容易猜到要填入 ScenarioInfo 的欄位進去，同時能透過語意反推填入的來源是 Scenario 身上有的屬性。

那麼，用「文件」的角度去看型別，就可以得到兩種好處。第一種是對人類來說，更容易理解一段程式碼的實作、使用方式，另一種則是對 AI 來推測生成的內容，更容易正確的預測所需的內容。

Ruby 的 RBS 是在 Matz 認為未來會有更好的輔助工具時，選擇不讓 Ruby 內建型別的情境下產生的，如同寫測試我們可能會預期「都要測試」一樣，對於有 AI 輔助的世界，撰寫 RBS 的意義可能更多在於「描述規格（約定）」這件是情上，也就是一種文件

加速開發

目前來看，Copilot 的價值是幫助工程師省下打字和查閱程式碼的時間，因為我們不需要耗費腦力去翻閱過往的程式實做，只需用精確的關鍵字描述意圖，就能根據以往的物件推導出接近預期的程式碼。這跟今年ＷebConf 保哥的演講活用 GitHub Copilot 開發 Web 應用程式的結論基本上是一樣的。

想讓 AI 做到輔助的效果，對工程師的基本功要求還是非常高的。舉例來說，我們用中文跟 ChatGPT 對話時，大多可以得到中文的回應，用英文的話就會得到英文的回應。這就表示，我們用一個比較差的寫法開頭，那麼就會得到訓練資料中比較差的做法。

在 AI 輔助開發的情境中，一個提示的品質好壞還是取決於工程師起頭撰寫的程式碼是怎樣的，剩下的部分則仰賴專案中已存在的部分做為參考，那麼命名、定義等資訊足夠明確的狀況下，產生出來的程式碼品質也會更高、更準確，最後才會讓開發的效率得到提升。

除此之外，有一類型的註解我也會選擇去撰寫，那就是 RDoc 或者 TSDoc 這類基於註解產生的文件，這跟型別文件的好處是類似的，對人類更容易理解，對 AI 來說還因為多了說明和範例，在推導程式碼的效果可能還會更好。

目前是還沒有感受到 Copilot 會去掃套件中的註解範例來輔助生成的樣子，也許未來會有這樣的機制，那麼許多「不知道」的使用方式也許也能被涵蓋到，讓我們能更加善用套件來減少重複造輪子的狀況。

Rails 部署實踐 - 使用 GitHub Actions 自動化建置

contact@aotoki.me (蒼時弦也) — Fri, 10 Jun 2022 00:00:00 +0800

GitHub Actions 跟 GitLab CI 有著不少差異，雖然在這類工具中不外乎就是生產線（Pipeline）和任務（Task）的搭配使用，然而每套系統都還是有著不同的設計可以使用。

因為我比較常使用 GitLab CI 因此有著完整的樣板專案可以使用，目前還在建置 GitHub Actions 的樣板，這篇文章主要是我在 GitHub 上面的專案所彙整出來的使用技巧。

GitHub Actions 基礎概念

跟 GitLab CI 不同的地方在於，整個 GitHub Actions 允許有多個工作流程（Ｗorkflows）的存在，我們可以理解為允許多個生產線（也就是 .gitlab-ci.yml 設定）的狀態，基於這樣的前提我們就能把不同的任務拆分出來處理。

GitLab CI 其實也能夠利用 Child Pipeline 的方式來實現這件事情。

基本結構

我們只需要在 .github/workflows/ 目錄下增加像是 containerize.yml 的設定檔即可。

 1name: Containerize # 名稱
 2
 3on: # 啟動條件
 4 push:
 5 branches:
 6 - main
 7
 8jobs: # 任務
 9 assets:
10 runs-on: ubuntu-latest # 運行環境
11 steps:
12 # ...

基本結構大致上是類似的，然而我們沒有了階段（Stage）的設定，每個工作流程基本上是會同步的進行，但是可以利用 on 的觸發來設定要在什麼情況下才運行。

至於 Job（任務）的使用基本上是類似的，只不過在 GitHub Actions 中不是使用容器而是直接使用 Runner 來運行。

自動建置 Rails 鏡像

想在 GitHub Actions 自動建置鏡像某方面來說比在 GitLab CI 來說是更容易的，因為有許多現成的 Action（動作）模組可以使用，然而每個模組的作者在文件上的撰寫品質不一，因此也不一定容易使用，這邊我們使用的基本上都是官方的套件，因此還不算難使用。

Assets Precompile

同樣的，我們希望在容器化之前就先把素材預先編譯完畢，因此第一個加入的就是 Assets Precompile 的任務。

 1name: Containerize
 2
 3on:
push:
branches:
- main
 7
 8env: # 共通環境變數
RUBY_VERSION: '2.7.5'
NODE_VERSION: '16'
RAILS_ENV: production
RAILS_MASTER_KEY: ${{ secrets.RAILS_SECRET_KEY }}
13
14jobs:
assets:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2 # 預先做成腳本的動作，不需要自己下命令
- name: Set up Ruby
uses: ruby/setup-ruby@v1
with: # 預先動作的額外設定，這邊是設定 Ruby 版本
ruby-version: ${{ env.RUBY_VERSION }}
bundler-cache: true
- name: Set up Node
uses: actions/setup-node@v2
with:
node-version: ${{ env.NODE_VERSION }}
cache: 'yarn'
- run: yarn install # 直接執行命令的情況
- run: bundle exec rake assets:precompile
- name: Archive precompiled assets
uses: actions/upload-artifact@v3
with:
name: assets
path: public/
retention-days: 7

在上面這段大多是使用 GitHub、Ruby、Node.js 官方預先準備好的動作來處理，假設是一些主流的語言、工具大多都已經有先寫好的動作，可以直接當作是模組載入使用。

在這個階段我們基本上就是把 Ruby、Node.js 都安裝一遍，然後執行 rake assets:precompile 預先編譯素材，最後使用 Artifacts（生成物）功能將編譯好的檔案上傳。

製作容器

接下來我們要進行容器化的處理，基本上大部分的命令都已經有預先製作好的版本，我們只需要套用正確的設定即可。雖然 Docker 可以使用 Buildx（Buildkit 的封裝）然而卻無法使用 Registry 版本的封裝，這會讓容器化的速度稍微變慢，不過還在可以接受的範圍之內。

 1# ...
 2
 3env:
# ...
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}
 7
 8jobs:
# ...
build-and-push-image:
runs-on: ubuntu-latest
needs: assets
permissions:
contents: read
packages: write
16
steps:
- name: Checkout repository
uses: actions/checkout@v2
20
- name: Download precompiled assets
uses: actions/download-artifact@v3
with:
name: assets
path: public/
26
- name: Log in to the Container registry
uses: docker/login-action@v1
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
33
- name: Extract metadata (tags, labels) for Docker
id: meta
uses: docker/metadata-action@v3
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
tags: |
type=sha
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=ref,event=branch
- name: Build and push Docker image
uses: docker/build-push-action@v2
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:main
cache-to: type=inline

因為 GitHub 有也提供 Registry 的伺服器，因此我們可以直接使用自動設定好的帳號密碼登入來上傳，跟 GitLab CI 版本不太一樣的地方是我們的鏡像標籤。

在 GitLab CI 的版本中，我們會產生類似 registry.gitlab.com/example/example:c5e6528 的鏡像標籤，然而在 GitHub Actions 預先製作好的命令中，產生的是 sha-c5e6528 這樣的標籤，然而這不影響我們使用以及控制版本來進行部署。

在這裡我們對 tags 做了三個選想，分別是 sha 為基礎的標籤、1.0.0 和 1.0 以版本為主的標籤，以及以 Branch 名稱的標籤，這個規則基本上是對應大部分 Docker 鏡像的規則，可以依照自己的需求調整。

完成這些設定之後，我們就可以在 GitHub 上面自動的產生 Rails 的容器鏡像，如果是公開的專案就能夠直接透過 GitHub 提供的 Registry 來直接使用。

如果想在第一時間收到更新，歡迎訂閱弦而時習之在這系列文章更新時收到通知，如果有希望了解的知識，可以利用Rails 部署實踐回饋表單告訴我。

Travis CI 的 Deploy 功能

contact@aotoki.me (蒼時弦也) — Tue, 25 Feb 2014 00:00:00 +0800

最近收到一個 Issue 是關於我製作的 Heroku Buildpacks 有問題，沒辦法使用 Travis CI 的 Deploy 功能。

因為寫 Test 的習慣養成挺困難的，再加上獨自開發與大多是半遊玩性質的關係，其實幾乎沒有使用 Travis CI 的習慣，不過這次因為這個 Issue 我稍微研究了 Travis CI 的功能以及 Deploy 功能。

這算是一個很方便的功能，尤其是網站專案來說，如果在 Deploy 後馬上就發生問題，也是非常不方便。那麼，一般 Git 的專案來說，我們通常都是直接進行 Deploy 即使在本機事先做過一次測試，但是總是會有忘記的時候。

此時，透過持續整合服務的自動 Deploy 功能來協助，就可以在確保所有測試都沒問題的狀況下才進行 Deploy 也比較能夠自動化。

那麼，我們該如何開始呢？

如果已經在使用 Travis CI 可以直接打開 .travis.yml 檔案加入 deploy 的設定項。

1deploy:
provider: Heroku
api_key: xxx
app: my-auto-deploy-app

或者安裝 Travis CI 的 Command Line Tools 使用 travis setup Heroku 來自動生成。不過這需要先有 .travis.yml 檔案存在，如果沒有的話可先使用 travis init 來進行初始化。

不過，如果直接將 API Key 以明碼儲存在 Public 的 Repository 上其實有點不妥，因此可以使用 travis encrypt 先行加密。

travis encrypt travis encrypt $(Heroku auth:token)

我們就會得到一串加密的字串（大概是用 Travis CI 上面的 Public Key 加密的，因此不用擔心會被解開，擁有 Private Key 的只有 Travis CI 本身。）

之後修改 .travis.yml 即可。

1deploy:
provider: Heroku
api_key:
secure: encrypted-api-key
app: my-auto-deploy-app

上面基本上就是最為基本的使用，不過要注意的是，假設測試的版本有多個（Ex. PHP 5.4, PHP 5.5）那麼這個動作也會被執行兩次（預設情況）

後面就來談談官方文件上所敘述的其他運用方式吧！（這個 Deploy 功能也支援像是 OpenShift, AWS 等，可以依照情況使用。）

不同 Branch Deploy 到不同 Heroku APP

這個情況像是有 Production 之外，也許還會有 Staging 供內部測試時，就很方便。

1deploy:
provider: Heroku
api_key:
secure: encrypted-api-key
app:
production: production-app
staging: staging-app

其實概念挺簡單好懂的，就是 branch: app 的格式。（也支援 Deploy 到不同 Heroku 帳號，用法一樣只是改為寫在 api_key 項目下。）

僅有部分 Branch 需要 Deploy

一般來說我們的 Development 不會需要 Deploy 出去，但是每次跑 CI 的時候都會用 Development 去 Deploy 非常不方便，因此可以使用 on 來做設定。

1deploy:
provider: Heroku
api_key:
secure: encrypted-api-key
app: my-auto-deploy-app
on: production

使用 travis setup Heroku 的話，會發現預設是 on 一個 repo 不過文件上似乎沒有詳細敘述，不過這個選項是支援多選的。

Deploy 後運行某些 Command

像是 Rails / Laravel 這類 Framework 在產生 Migration 一段時間後進入 Deploy 程序，就很容易忘記下 migrate 這個指令，我自己就碰過因為忘記下而讓網站死掉的情況⋯⋯

Travis CI 也很貼心地提供這個功能（甚至還有 after_deploy 可以做後續處理）

1deploy:
provider: Heroku
api_key:
secure: encrypted-api-key
app: my-auto-deploy-app
run:
- "rake db:migrate"
- "rake assets:precompile"

如果只需要 rake db:migrate 直接寫在 run 後面就可以了。

整體來說很好理解，不過這個功能卻解決了網站在 Deploy 上的問題。（像是需要使用 Capistrano 之類的來輔助才能完成之類的，如果是 PHP 專案也可以用 FTP 來上傳。）