# 為 Scrapy 貢獻
> 譯者:[OSGeo 中國](https://www.osgeo.cn/)
重要
在https://docs.scrapy.org/en/master/contributing.html上仔細檢查您是否正在閱讀此文檔的最新版本。
有很多方法可以讓你的生活一團糟。以下是其中一些:
* 關于Scrapy的博客。告訴全世界你是如何使用Scrapy的。這將有助于新來者提供更多的示例,并有助于 Scrapy 的項目增加其可見性。
* 報告Bug并請求 [issue tracker](https://github.com/scrapy/scrapy/issues) ,嘗試遵循 [Reporting bugs](#reporting-bugs) 下面。
* 提交新功能和/或錯誤修復的補丁。請閱讀 [編碼補丁](#writing-patches) 和 [Submitting patches](#id2) 下面是關于如何編寫和提交補丁的詳細信息。
* 加入 [Scrapy subreddit](https://reddit.com/r/scrapy) 分享你對如何改善垃圾的想法。我們總是樂于接受建議。
* 回答一些瑣碎的問題 [Stack Overflow](https://stackoverflow.com/questions/tagged/scrapy) .
## 報告錯誤
注解
請報告安全問題 **only** 發送至scrapy-[security@googlegroups.com](mailto:security%40googlegroups.com)。這是一個私人列表,只對受信任的垃圾開發者開放,其檔案不公開。
寫得好的bug報告非常有用,因此在報告新bug時,請記住以下指導原則。
* 檢查 [FAQ](faq.html#faq) 首先看看你的問題是否在一個眾所周知的問題中得到解決。
* 如果您對 Scrapy 的使用有一般性問題,請在 [Stack Overflow](https://stackoverflow.com/questions/tagged/scrapy) (使用“ Scrapy ”標簽)。
* 檢查 [open issues](https://github.com/scrapy/scrapy/issues) 查看問題是否已報告。如果有,不要駁回報告,而是檢查記錄和評論。如果您有其他有用信息,請留言或考慮 [sending a pull request](#writing-patches) 修理好了。
* 搜索 [scrapy-users](https://groups.google.com/forum/#!forum/scrapy-users) 列表和 [Scrapy subreddit](https://reddit.com/r/scrapy) 看看是否在那里討論過,或者你不確定你所看到的是否是一個bug。你也可以在 `#scrapy` IRC通道。
* 寫 完整、可復制、特定的錯誤報告. 測試用例越小越好。請記住,其他開發人員不會讓您的項目復制該bug,因此請包括復制該bug所需的所有相關文件。例如,請參見StackOverflow的《創建 [Minimal, Complete, and Verifiable example](https://stackoverflow.com/help/mcve) 展示問題。
* 提供一個完整的可復制示例的最棒的方法是發送一個pull請求,該請求將一個失敗的測試用例添加到Scrapy測試套件中(請參見 [正在提交修補程序](#submitting-patches) )即使你不打算自己解決這個問題,這也是有幫助的。
* 包括的輸出 `scrapy version -v` 因此,開發人員在您的bug上準確地知道它發生在哪個版本和平臺上,這通常對復制它非常有幫助,或者知道它是否已經被修復了。
## 編碼補丁
補丁編寫得越好,它被接受的機會就越高,合并的速度就越快。
寫得好的補丁應該:
* 包含特定更改所需的最小代碼量。小補丁更容易查看和合并。因此,如果您進行了多個更改(或錯誤修復),請考慮為每個更改提交一個補丁。不要將多個更改折疊為單個修補程序。對于較大的更改,請考慮使用修補程序隊列。
* 通過所有單元測試。見 [Running tests](#running-tests) 下面。
* 包括一個(或多個)測試用例,檢查修復的錯誤或添加的新功能。見 [Writing tests](#writing-tests) 下面。
* 如果要添加或更改公共(文檔化)API,請在同一補丁中包含文檔更改。見 [Documentation policies](#documentation-policies) 下面。
## 正在提交修補程序
提交補丁的最佳方法是發布 [pull request](https://help.github.com/send-pull-requests/) 在Github上,可以選擇先創建一個新問題。
記住解釋什么是固定的或新的功能(它是什么,為什么需要它,等等)。您包含的信息越多,核心開發人員就越容易理解和接受您的補丁。
您也可以在創建補丁之前討論新的功能(或bug修復),但是準備好一個補丁來說明您的論點并表明您已經在主題中添加了一些額外的思想總是很好的。一個好的起點是在Github上發送一個拉請求。它可以很簡單地說明您的想法,并將文檔/測試留到稍后,在這個想法被驗證和證明是有用的之后。或者,您可以在 [Scrapy subreddit](https://reddit.com/r/scrapy) 先討論你的想法。
有時,對于您想要解決的問題,有一個現有的請求請求,由于某種原因而停止。通常拉請求的方向是正確的,但更改是由 Scrapy 維護人員請求的,而原始拉請求作者沒有時間處理它們。在這種情況下,考慮接受這個拉請求:打開一個新的拉請求,其中包含來自原始拉請求的所有提交,以及解決所提出問題的其他更改。這樣做有很大的幫助;一旦原作者被承認遵守了自己的承諾,就不會被認為是不禮貌的。
您可以通過運行 `git fetch upstream pull/$PR_NUMBER/head:$BRANCH_NAME_TO_CREATE` (將“上游”替換為Scrapy存儲庫的遠程名稱, `$PR_NUMBER` 帶有拉請求的ID,以及 `$BRANCH_NAME_TO_CREATE` 使用要在本地創建的分支的名稱)。另請參見:[https://help.github.com/articles/checking](https://help.github.com/articles/checking) out pull requests locally/在本地修改非活動的pull請求。
在編寫Github Pull請求時,請盡量保持標題簡短但具有描述性。例如,對于bug 411:“如果啟動請求中出現異常,則scrapy將掛起”首選“當啟動請求中出現異常時修復掛起”(而不是“修復為411”)。完整的標題使瀏覽問題跟蹤器變得容易。
最后,試著保持審美的變化( [**PEP 8**](https://www.python.org/dev/peps/pep-0008) 合規性、未使用的進口刪除等)與功能更改分開提交。這將使pull請求更容易審查,更容易合并。
## 編碼風格
編寫要包含在Scrapy中的代碼時,請遵循以下編碼約定:
* 除非另有規定,遵循 [**PEP 8**](https://www.python.org/dev/peps/pep-0008) .
* 如果可以提高代碼的可讀性,可以使用長度超過80個字符的行。
* 不要在您貢獻的代碼中輸入您的名字;Git提供了足夠的元數據來標識代碼的作者。有關安裝說明,請參閱https://help.github.com/articles/setting-your-username-in-git/。
## 文檔策略
對于API成員(類、方法等)的參考文檔,請使用docstring并確保sphinx文檔使用 [autodoc](http://www.sphinx-doc.org/en/stable/ext/autodoc.html) 用于拉取docstrings的擴展。API參考文檔應該是面向IDE的:簡短,切中要害,它可能提供簡短的示例。
其他類型的文檔(如教程或主題)應包含在 `docs/` 目錄。這包括特定于API成員的文檔,但超出了API參考文檔。
在任何情況下,如果文檔字符串中包含某些內容,請使用 [autodoc](http://www.sphinx-doc.org/en/stable/ext/autodoc.html) 擴展名,用于將docstring拉入文檔,而不是在 `docs/` 目錄。
## 測驗
測試是使用 [Twisted unit-testing framework](https://twistedmatrix.com/documents/current/core/development/policy/test-standard.html) ,運行測試需要 [tox](https://pypi.python.org/pypi/tox) .
### 運行試驗
確保你最近有足夠的 [tox](https://pypi.python.org/pypi/tox) 安裝:
> `tox --version`
如果您的版本早于1.7.0,請先更新:
> `pip install -U tox`
要運行所有測試,請轉到Scrapy源代碼的根目錄并運行:
> `tox`
運行特定的測試(比如 `tests/test_loader.py` 用途:
> `tox -- tests/test_loader.py`
查看覆蓋率報告安裝 [coverage](https://pypi.python.org/pypi/coverage) ( `pip install coverage` 然后運行:
> `coverage report`
見輸出 `coverage --help` 獲取更多選項,如HTML或XML報告。
### 寫作測試
所有功能(包括新功能和錯誤修復)都必須包含一個測試用例,以檢查它是否按預期工作,因此如果您希望補丁能夠更快地被接受,請包含對它們的測試。
Scrapy使用單元測試,位于 [tests/](https://github.com/scrapy/scrapy/tree/master/tests) 目錄。它們的模塊名通常類似于所測試模塊的完整路徑。例如,項目加載器代碼位于::
```py
scrapy.loader
```
他們的單元測試在:
```py
tests/test_loader.py
```
- 簡介
- 第一步
- Scrapy at a glance
- 安裝指南
- Scrapy 教程
- 實例
- 基本概念
- 命令行工具
- Spider
- 選擇器
- 項目
- 項目加載器
- Scrapy shell
- 項目管道
- Feed 導出
- 請求和響應
- 鏈接提取器
- 設置
- 例外情況
- 內置服務
- Logging
- 統計數據集合
- 發送電子郵件
- 遠程登錄控制臺
- Web服務
- 解決具體問題
- 常見問題
- 調試spiders
- Spider 合約
- 常用做法
- 通用爬蟲
- 使用瀏覽器的開發人員工具進行抓取
- 調試內存泄漏
- 下載和處理文件和圖像
- 部署 Spider
- AutoThrottle 擴展
- Benchmarking
- 作業:暫停和恢復爬行
- 延伸 Scrapy
- 體系結構概述
- 下載器中間件
- Spider 中間件
- 擴展
- 核心API
- 信號
- 條目導出器
- 其余所有
- 發行說明
- 為 Scrapy 貢獻
- 版本控制和API穩定性