free-programming-books/docs/CONTRIBUTING-zh_TW.md

*[閱讀其他語言版本的文件](README.md#nslations)*


## 貢獻者許可協議

請遵循此 [許可協議](../LICENSE) 參與貢獻。


## 貢獻者行為準則

請同意並遵循此 [行為準則](CODE_OF_CONDUCT.md) 參與貢獻。([translations](README.md#nslations))


## 概要

1. "一個可以輕易下載一本書的連結" 並不代表它導向的就是 *免費* 書籍。 請只提供免費內容。 確信你所提供的書籍是免費的。我們不接受導向 *需要* 工作電子郵件地址才能獲取書籍頁面的連結，但我們歡迎有需求這些連結的列表。

2. 你不需要會 Git：如果你發現了一些有趣的東西 *尚未出現在此 repo* 中，請開一個 [Issue](https://github.com/EbookFoundation/free-programming-books/issues) 進行主題討論。
    * 如果你已經知道 Git，請 Fork 此 repo 並提交 Pull Request (PR)。

3. 這裡有六種列表，請選擇正確的一項：

    * *Books* ：PDF、HTML、ePub、基於 gitbook.io 的網站、Git 的 repo 等。
    * *Courses* ：課程是一種學習素材，而不是一本書 [This is a course](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/)。
    * *Interactive Tutorials* ：一個互動式網站，允許用戶輸入程式碼或指令並執行結果。例如：[Try Haskell](http://tryhaskell.org)，[Try GitHub](http://try.github.io)。
    * *Playgrounds* : Playgrounds 是學習程式設計的線上互動式網站、遊戲或桌面軟體。你可以在上面編寫、編譯、運行或分享程式碼片段。 Playgrounds 通常允許你 fork 程式碼然後在其中盡情的編寫程式碼。
    * *Podcasts and Screencasts* ：Podcast 和影音。
    * *Problem Sets & Competitive Programming* ：一個網站或軟體，讓你透過解決簡單或複雜的問題來評估你的程式技能，可能有程式碼檢查，或與其他用戶比對结果。

4. 確保遵循下方的 [基本準則](#基本準則)，並遵循此 repo 文件的 [Markdown 規定格式](#規定格式)。

5. GitHub Actions 將運行測試，以確保你的列表是 **按字母顺序排列** 的，並 **遵循格式化規則**。請 **確保** 你的更改通過該測試。


### 基本準則

* 確保你提交的每一本書都是免費的。如有需要請 Double-check。如果你在 PR 中註明為什麼你認為這本書是免費的，這對管理員是很有幫助的。
* 我們不接受儲存在 Google Drive、Dropbox、Mega、Scribd、Issuu 和其他類似文件上傳平台上的文件。
* 請按照字母順序插入連結, 如 [下方敘述](#alphabetical-order).
* 使用最權威來源的連結(意思是原作者的網站比編輯的網站好，比第三方網站好)。
    * 沒有文件託管服務(包括(但不限於) Dropbox 和 Google Drive 連結)。
* 優先選擇使用 `https` 連結，而不是 `http` 連結 -- 只要它們位於相同的網域並提供相同的内容。
* 在網域根目錄上，去掉尾末的斜槓：使用 `http://example.com` 代替 `http://example.com/`。
* 優先選擇最短的連結：使用 `http://example.com/dir/` 比使用 `http://example.com/dir/index.html` 更好。
    * 不要提供短連結
* 優先選擇使用 "current" 連結代替有 "version" 連結：使用 `http://example.com/dir/book/current/` 比使用 `http://example.com/dir/book/v1.0.0/index.html` 更好。
* 如果一個連結存在過期的證書/自簽名證書/SSL問題的任何其他類型：
    1. *replace it* ：如果可能的話，將其 *替換* 為對應的 `http` (因為在移動設備上接受異常可能比較複雜)。
    2. *leave it* ：如果沒有`http`版本，但仍然可以通過`https`造訪連結，則在瀏覽器中添加異常或忽略警告。
    3. *remove it* ：上述狀況以外則刪除掉它。
* 如果一個連結以多種格式存在，請添加一個單獨的連結，並註明每種格式。
* 如果一個資源存在於Internet上的不同位置
    * 使用最權威來源的連結(意思是原始作者的網站比編輯的網站好，比第三方網站好)。
    * 如果它們連結到不同的版本，你認為這些版本差異很大，值得保留，那麼添加一個單獨的連結，並對每個版本做說明(參考 [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) 有助於格式化問題的討論)。
* 相較一個比較大的提交，我們更傾向於原子提交(通過添加/删除/修改進行一次提交)。在提交PR之前没有必要壓縮你的提交。(為了維護人員的方便，我們永遠不會執行這個規則)。
* 如果一本書比較舊，請在書名中註明出版日期。
* 包含作者的名字或適當的名字。中文版本可以用 “`等`” (“`et al.`”) 縮短作者列表。
* 如果一本書還没有完成，並且仍在編寫中，則需添加 “`in process`” 符號，參考 [下文](#in_process) 所述。
- if a resource is restored using the [*Internet Archive's Wayback Machine*](https://web.archive.org) (or similar), add the "`archived`" notation, as described [below](#archived). The best versions to use are recent and complete.
* 如果在開始下載之前需要電子郵件地址或帳户設置，請在括號中添加合適的語言描述，例如：`(*需要* 電子郵件，但不是必需的)`。


### 規定格式

* 所有列表都是 `.md` 文件。試着學習 [Markdown](https://guides.github.com/features/mastering-markdown/) 語法。它很容易上手！
* 所有的列表都以索引開始。它的作用是列出並連結所有的 sections (章節/段落)或 subsections (子段落/子章節)。務必遵循字母順序排列。
* Sections (章節/段落)使用3級標題(`###`)，subsections (子段落/子章節)使用4級標題 (`####`)。

整體思維為：

* `2` ：新添加的 Section 與末尾連結間必需留有 `2` 個空行
* `1` ：標題和第一個連結之間必需留有 `1` 個空行的空行
* `0` ：任何兩個連結之間不能留有任何空行
* `1` ：每個 `.md` 文件末尾必需留有 `1` 個空行

舉例：

```text
[...]
* [一本很有用的書](http://example.com/example.html)
                                (空行)
                                (空行)
### 電子書種類標題
                                (空行)
* [Another 很有用的書](http://example.com/book.html)
* [Other 有用的書](http://example.com/other.html)
```

* 在 `]` 和 `(` 之間不要留有空格：

    ```text
    錯誤：* [一本很有用的書] (http://example.com/book.html)
    正確：* [一本很有用的書](http://example.com/book.html)
    ```

* 如果包括作者，請使用' - '(由單個空格(英文半型)包圍的破折號)：

    ```text
    錯誤：* [一本很有用的書](http://example.com/book.html)- 張顯宗
    正確：* [一本很有用的書](http://example.com/book.html) - 張顯宗
    ```

* 在連結和電子書格式之間放一個空格：

    ```text
    錯誤：* [一本很有用的書](https://example.org/book.pdf)(PDF)
    正確：* [一本很有用的書](https://example.org/book.pdf) (PDF)
    ```

* 如需備注或注解，請使用英文半型括號`( )`：

    ```text
    錯誤：* [一本很有用的書](https://example.org/book.pdf) （繁體中文）
    正確：* [一本很有用的書](https://example.org/book.pdf) (繁體中文)
    ```

* 作者在電子書格式之前：

    ```text
    錯誤：* [一本很有用的書](https://example.org/book.pdf)- (PDF) 張顯宗
    正確：* [一本很有用的書](https://example.org/book.pdf) - 張顯宗 (PDF)
    ```

* 多重格式：

    ```text
    錯誤：* [一本很有用的書](http://example.com/)- 張顯宗 (HTML)
    錯誤：* [一本很有用的書](https://downloads.example.org/book.html)- 張顯宗 (download site)
    正確：* [一本很有用的書](http://example.com/) - 張顯宗 (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html)
    ```

* 多作者，多譯者時，請使用中文 `、` 進行分隔，在譯者名字後請使用英文半型括號包圍的 `(翻譯)`，可以用 “等” 縮短作者列表：

    ```text
    錯誤：* [一本很有用的書](https://example.org/book.pdf) - 張顯宗，岳綺羅
    正確：* [一本很有用的書](https://example.org/book.pdf) - 張顯宗、岳綺羅(翻譯)
    正確：* [一本很有用的書](https://example.org/book.pdf) - 張顯宗、岳綺羅、顧玄武、出塵子 等
    ```

* 在舊書的標題中包括出版年份：

    ```text
    錯誤：* [一本很有用的書](https://example.org/book.html) - 張顯宗 - 1970
    正確：* [一本很有用的書 (1970)](https://example.org/book.html) - 張顯宗
    ```

* <a id="in_process"></a>編寫(翻譯)中的書籍：

    ```text
    正確：* [即將出版的一本書](http://example.com/book2.html) - 張顯宗 (HTML) *(:construction: 編寫中)*
    正確：* [即將出版的一本書](http://example.com/book2.html) - 張顯宗 (HTML) *(:construction: 翻譯中)*
    ```

- <a id="archived"></a>Archived link:

    ```text
    正確: * [A Way-backed Interesting Book](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archived)*
    ```

### 依照字母排序

- 當出現多個相同字母開頭的標題時，則照第二個字母排序，以此類推。例如：`aa` 排在 `ab` 前面。
- `one two` 排在 `onetwo` 前面。

如果你看到錯誤的連結，請檢查 linter 的錯誤訊息來找到哪一行順序需要交換。


### 注意事項

雖然基本原則相對簡單，但我們列出的資源種類繁多。以下是我們如何處理這些多樣性的說明。


#### 元數據（Metadata）

我們的列表僅提供最基本的元數據：標題、網址、創作者、平台以及存取說明。


##### 標題

- 禁止自行創造標題。我們儘量從資源本身取得標題，並提醒貢獻者避免在非必要情況下編造或修改標題。對於較早的作品，如果它們主要具歷史價值，可以在標題後加上括號中的年份，方便用戶判斷是否感興趣。
- 禁止使用全部大寫的標題。一般來說，使用標題大小寫是合適的，但如果您不確定，請按照來源中的大小寫格式撰寫。
- 禁止使用表情符號。


##### 網址

- 禁止使用縮網址。
- 網址中的追蹤碼必須移除。
- 國際網址應進行轉義處理。雖然瀏覽器網址欄通常會顯示為 Unicode，請務必使用複製貼上的方式保留正確格式。
- 若情況允許，應優先使用安全的網址（https），避免使用不安全的網址（http）。
- 我們不喜歡指向與所列資源無關的網頁，也不接受這類轉址鏈接。


##### 創作者

- 我們希望在適當的情況下標明免費資源的創作者，包括翻譯者！
- 對於翻譯作品，應標註原作者。我們建議使用 [MARC 貢獻者標註](https://loc.gov/marc/relators/relaterm.html) 來標示非作者的其他創作者，如以下範例所示：

    ```markdown
    * [中文翻譯版](http://example.com/book-zh.html) - John Doe, `trl.:` Mike The Translator
    ```

    在這裡，註記 trl.: 使用了 MARC 關係代碼來標示 “翻譯者”。
- 作者列表中的每個項目以逗號 `,` 分隔。
- 可以使用 “`et al.`” 來縮短作者列表。
- 創作者名稱不可添加鏈接。
- 對於彙編或混合作品，可能需要對 “創作者” 進行描述。例如，“GoalKicker” 或 “RIP Tutorial” 這類書籍會標註為 “`Compiled from StackOverflow documentation`”。


##### 平台與存取權限說明

- 課程。特別是在我們的課程列表中，平台是資源描述中重要的一部分。因為不同的課程平台有不同的功能與存取模式。雖然我們通常不會列出需要註冊才能訪問的書籍，但許多課程平台有一些功能必須登入帳戶才能使用。常見的課程平台包括 Coursera、EdX、Udacity 和 Udemy。如果課程依賴某個平台，應在括號中列出該平台名稱。
- YouTube。我們有許多課程由 YouTube 播放清單構成，但我們不會將 YouTube 列為平台，通常會列出 YouTube 創作者，這通常是該平台的子單位。
- YouTube 影片。我們通常不會鏈接單一的 YouTube 影片，除非該影片長於一小時，且結構類似於課程或教學。
- Leanpub。Leanpub 上的書籍有各種存取模式，有時書籍不需要註冊即可閱讀，有時則需要 Leanpub 帳戶來免費存取。鑑於書籍的質量及其存取模式的多樣性與變化，我們允許列出需要帳戶存取的書籍，並註明 `*(需要 Leanpub 帳戶或有效的電子郵件)*`。


#### 資源類型

決定資源歸屬於哪個列表的首要規則是看資源如何自我描述。如果它稱自己是一本書，那麼它就是一本書。


##### 我們不列出的資源類型

由於網際網路內容浩瀚無邊，我們的列表不包含以下內容：

- 部落格
- 部落格文章
- 文章
- 網站（除非該網站包含我們列出的大量資源）
- 不是課程或螢幕錄製的影片
- 書籍章節
- 書籍的試閱樣章
- IRC 或 Telegram 頻道
- Slack 或郵件列表

對於競賽編程的資源列表，資源類型的審核不會那麼嚴格。這個儲存庫（repository）的範圍由社群決定；如果您想對範圍進行更改或擴展，請通過提交 Issue 來提出建議。


##### 書籍與其他資源的區別

我們對書籍的定義並不那麼嚴格，但以下特徵通常表明該資源是書籍：

- 它有 ISBN（國際標準書號）
- 它有目錄
- 提供可下載的版本，特別是 ePub 文件
- 它有不同版本
- 它不依賴互動內容或影片
- 它試圖全面涵蓋某一主題
- 它是自成一格的

我們列出的許多書籍不一定具備這些特徵，具體情形取決於上下文。


##### 書籍與課程的區別

有時這兩者很難區分！

課程通常會有搭配的教材，這些教材會列在我們的書籍列表中。課程還包括講座、練習、測試、筆記或其他教學輔助資源。單一講座或影片本身不算是課程，PowerPoint 投影片也不算是課程。


##### 互動式教程與其他內容的區別

如果你可以將它列印出來並保留其精髓，那麼它就不算是互動式教程。


### 自動化測試

- 規定格式驗證是由 [GitHub Actions](https://docs.github.com/en/actions) 自動化進行，使用 [fpb-lint](https://github.com/vhf/free-programming-books-lint) 套件 (參閱 [`.github/workflows/fpb-lint.yml`](../.github/workflows/fpb-lint.yml))。
- 使用 [awesome_bot](https://github.com/dkhamsing/awesome_bot) 進行連結驗證。
- 可以藉由提交一個內容包含 `check_urls=file_to_check` 來觸發連結驗證:

    ```properties
    check_urls=free-programming-books.md free-programming-books-zh.md
    ```

- 您可以以一個空白區隔出想要進行驗證的檔案名稱來一次驗證多個檔案。
- 如果您一次驗證多個檔案，自動化測試的結果會是基於最後一個驗證的檔案。您的測試可能會因此通過，因此請詳加確認測試日誌。可以在 Pull Request 結果中點選"Show all checks" -> "Details" 來查看。