走進開源專案 - urlcat

robin發表於2022-03-01

大部分人都有個參與開源專案的夢，可專案在前卻不知如何下手？今日有幸遇到了可以下手的庫 — urlcat

Untitled.png

urlcat 只有 267 行程式碼的開源專案，卻收穫了 1.4 k 的 star，周下載量 1 w 以上，這是我目前遇到過原始碼最少的開源專案，下面就來一探究竟，看看每個檔案在專案中的作用。

Untitled 1.png

.github

image.png

從命名上看是 issue 和 pr 模板，這三個模板可以有效降低作者與使用者的溝通成本，高效解決問題，其中：

bug_report.md 描述：

  1. 什麼問題
  2. 如何復現該問題
  3. 預期的行為效果是什麼
  4. 截圖
  5. 桌面環境：什麼系統、什麼瀏覽器、什麼版本
  6. 手機環境：什麼裝置、什麼系統、什麼瀏覽器、什麼版本
  7. 問題上下文：作用在於說明該問題是否與其他問題有關聯

fature_request.md 描述：

  1. 你需要的功能是否與某個問題有關
  2. 描述下你想要的方案
  3. 描述你可能考慮過的代替方案
  4. 描述預製相關的功能 issue

pull_request_template.md 描述：

  1. PR 的功能概括
  2. PR 的詳情描述

docs

image.png

用 What、Why、How 精準闡述了專案的存在的意義。

  • What：是什麼？
  • Why：為什麼要做？
  • How：怎麼用

除此之外，還提供了詳細的 api 說明，以及告訴大家如何參與該專案，貢獻自己的程式碼。

src

存放原始碼的資料夾，之後會單獨寫一篇關於該原始碼的文章。

test

都說單元測試很重要，可都覺得寫單元測試費時費力，即便是區區幾百行程式碼，該作者依舊寫了如此詳細的單元測試，這是一種態度。

Untitled 4.png

.all-contributorsrc

一個專案能夠保持活力，持續不斷的發展，需要眾人的力量。

.editorconfig

有助於在不同的編輯器和 IDE 中保持一致的編碼樣式。

# 是否是頂級配置檔案，設定為 true 的時候才會停止搜尋.editorconfig 檔案
root = true

[*]
# 換行符型別
end_of_line = lf
# 是否讓檔案以空行結束
insert_final_newline = true
# 縮排方式
indent_style = space
# 縮排大小
indent_size = 2
# 編碼格式
charset = utf-8

.eslintignore

告訴 eslint 忽略特定檔案和目錄，不要對其進行檢測。

node_modules
dist
coverage

.eslintrc.js

eslint 配置檔案

module.exports = {
  env: {
    'node': true
  },
  root: true,
  parser: '@typescript-eslint/parser',
  plugins: [
    '@typescript-eslint',
  ],
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
  ],
  rules: {
    'object-curly-spacing': ['error', 'always'],
    'array-bracket-spacing': ['error', 'never'],
    'quotes': ['error', 'single'],
    'no-console': ['error'],
  }
};

關於 eslint 的配置已經有不少好文，感興趣的可以看看這篇文章。

相關文章：

.gitignore

提交程式碼時，需要忽略一些檔案時，該配置就很有用了

/node_modules
/dist
/dist-test
/.nyc_output
/coverage
.vscode

.npmignore

當需要釋出 npm 包時，可以忽略一些不需要釋出到 npm 的檔案。

/node_modules
/dist-test
/src
/docs
/test
/.travis.yml
/tsconfig.json
/tsconfig-test.json
/.nyc_output
/coverage

.travis.yml

一個持續整合服務的配置檔案

language: node_js
node_js:
  - lts/*
  - 14
  - 13
  - 12
  - 11
  - 10
script:
  - npm run lint
  - npm test
  - npm run coverage

關於持續整合服務，看看阮一峰老師的這篇文章就夠了。

相關文章：

CODE_OF_CONDUCT.md

第一次注意到這個檔案，搜了相關資料，原來是行為準則。看了篇博文也瞭解其作用。行為準則對開源社群的健康、可持續發展有著至關重要的影響。

相關文章：

CONTRIBUTING.md

貢獻指南，前面已提過。

LICENSE

開源許可證，授權他人與特定權利來使用的產品。防止那些拿來主義。怎麼選擇開源許可證，在這裡借用下阮一峰老師的一張圖。

Untitled 5.png

相關文章：

README.md

該作者的一份 README.md 基本涵蓋了之前提到的 docs 的所有內容，很簡潔，跟程式碼一樣簡潔??

jest.config.js

單元測試配置檔案，這也是我所欠缺的，之後會詳細學習一下。

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  coverageDirectory: 'coverage',
  collectCoverage: true,
  testMatch: [
    '**/test/**/*.ts'
  ],
  verbose: true,
  collectCoverageFrom: [
    '**/src/**/*.ts'
  ],
  testPathIgnorePatterns: [
    'dist.*\\.ts$'
  ]
}

相關文章：

package-lock.json

簡單理解，為了鎖定第三方包的版本號， 由於專案會依賴大量第三方包，第三方包也會依賴其他第三方包，當包更新了不相容的 api 時，在執行 npm install 之後，專案執行時，可能會發生意想不到的情況。

相關文章：

package.json

作為前端人，都再熟悉不過，分享幾個不常見，但很關鍵的配置：

指定 node 版本號：

{
  "engines": {
    "node": ">=8 <14"
  }
}

指定 npm 版本：

{
  "engines": {
    "npm": "~1.0.20"
  }
}

如果你打算髮佈一個 npm 包，files欄位可能會有用，指定釋出到 npm 中的檔案

鉤子，npm 指令碼有 pre 和 post 兩種鉤子。其作用執行某些特殊命令是觸發自動化指令碼，例如：

  • build 之前刪除 dist
  • publish 之前跑單元測試並打包專案
"scripts": {
    "clean": "shx rm -rf dist",
    "prebuild": "npm run clean",
    "build": "tsc -p .",
    "test": "jest",
    "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
    "coverage": "cat ./coverage/lcov.info | coveralls",
    "prepublish": "npm test && npm run build",
    "docs": "docsify serve docs --open"
  },

相關文章：

renovate.json

一種似曾相識的感覺，是它，就是它。

Untitled 6.png

Untitled 7.png

Renovate 是一個開源工具，用於自動化：

  • 檢測儲存庫中的依賴項（開源和私有/閉源）
  • 檢查是否有依賴更新
  • 建立提交和合並/拉取請求以更新依賴項
  • ……

tsconfig.json

當使用 typescript 開發專案時就會用到該配置檔案。

相關文章：

總結

除原始碼和單元測試之外，對其他檔案的用途都做了說明，做開源不易，當我們信手拈來之時，這些開源專案作者付出了太多。一群來自世界各地的人，共同完成一件事，除了專業技能之外，看到更多的是一種態度。

參考文章：

相關文章