向 CodeIgniter 貢獻(xiàn)你的力量

向 CodeIgniter 貢獻(xiàn)你的力量

• 編寫 CodeIgniter 的文檔
• Developer's Certificate of Origin 1.1

CodeIgniter 是一個社區(qū)驅(qū)動的項(xiàng)目，它會接受從社區(qū)里貢獻(xiàn)的文檔和代碼。 這些貢獻(xiàn)都是通過 GitHub 上?CodeIgniter 代碼倉庫?的 Issues 或者?Pull Requests?的形式來完成的。

Issues 是一種快速提交 bug 的方式，如果你發(fā)現(xiàn)了一個 CodeIgniter 的 bug 或文檔錯誤，那么請先 看看下面這幾點(diǎn)：

• 是否已經(jīng)存在一個打開的 Issue
• 該 Issue 是否已經(jīng)被修復(fù)了（檢查下 delevop 分支的代碼，或者已關(guān)閉的 Issues）
• 這個 bug 很明顯你一個人就能修復(fù)嗎？

提交 Issues 是非常有用的，但是更好的做法是發(fā)起一個 Pull Request ，具體的做法是先 fork 主倉庫的代碼，然后將修改的代碼提交到你自己的副本中。這需要你會使用版本控制系統(tǒng) Git 。

支持

請注意，GitHub 并不是用來回答一般的技術(shù)支持類問題的！

如果你在使用 CodeIgniter 的某個功能時遇到了問題，請到論壇提問。

如果你不知道自己做的對不對，或者不確定自己找到了一個 bug ，也請先到論壇里提問。

提交好問題的技巧

使用描述性的標(biāo)題（如：解析器類在處理逗號時出錯），而不是使用模糊不清的標(biāo)題（如：我的代碼出錯了）

在一份報(bào)告中只提交一個問題。

在問題中指出 CodeIgniter 的版本（如：3.0-develop），以及出問題的組件（如果你知道的話）（如：解析器類）

解釋清楚你希望出現(xiàn)什么結(jié)果，以及當(dāng)前出現(xiàn)的結(jié)果是什么。 如果有錯誤信息的話，并附上錯誤信息和堆棧信息。

如果有助于闡述你的問題的話，你可以包含少量的代碼片段。 如果有大量的代碼或截圖的話，可以使用類似于 pastebin 或者 dropbox 這樣的服務(wù)，不要在問題報(bào)告中包含這些內(nèi)容。 為這些內(nèi)容設(shè)置一個合理的過期時間，至少在問題被解決或關(guān)閉之前確保它們能訪問。

如果你知道如何修復(fù)該問題，你可以 fork 并在你自己的分支中修改，然后提交一個 pull request 。 并將上面說的問題報(bào)告作為 pull request 的一部分。

如果能在問題報(bào)告中描述問題重現(xiàn)的詳細(xì)步驟，那將是極好的。 如果你還能提供一個單元測試用例來重現(xiàn)該錯誤，那將更好，因?yàn)檫@給了修復(fù)這個問題的人一個更清晰的目標(biāo)。

指導(dǎo)手冊

這里是如何提交 Pull Requests 的一些指南，如果你提交的 Pull Requests 沒有遵循這篇指南中提出的這些， 你的提交可能會被拒絕并要求你重新提交。這可能聽起來有點(diǎn)難，但是為了保證我們的代碼質(zhì)量這是必須要做的。

PHP 代碼規(guī)范

所有的代碼都必須符合?代碼規(guī)范指南，它其實(shí)就是?Allman 縮進(jìn)風(fēng)格?加上下劃線規(guī)則以及可讀的操作符。遵循代碼規(guī)則可以讓代碼的風(fēng)格保持一致，同時也意味著代的更可讀性更好。

文檔

如果你的修改同時也需要在文檔中另加說明，那么你也需要在文檔中加上它。新的類、方法、參數(shù)、默認(rèn)值的修改 等等這些都需要對文檔做相應(yīng)的調(diào)整。每一處修改也必須要在代碼的變更日志（change-log）中進(jìn)行更新。另外， PHP 的文檔注釋塊（PHPDoc blocks）也要修改。

兼容性

CodeIgniter 推薦使用 PHP 5.4 或更高的版本，但是同時它也對 PHP 5.2.4 保持兼容，所以所有提交的代碼都必須 滿足這一點(diǎn)。如果你用到了 PHP 5.3 （或以上版本）中的函數(shù)或新特性，這些代碼需要回退到 PHP 5.2.4 版本的。

分支

CodeIgniter 使用了?Git-Flow?分支模型， 這要求所有的 pull request 應(yīng)該提交到 develop 分支，develop 分支是正在開發(fā)的打算在下一版發(fā)布的分支， master 分支總是包含最新的穩(wěn)定版并保持干凈，這樣可以在譬如出現(xiàn)緊急安全漏洞時快速的在 master 分支代碼 上打上補(bǔ)丁并發(fā)布新的版本，而無需擔(dān)心新加的功能會影響它。正是因?yàn)檫@個原因，所有的提交都應(yīng)該在 develop 分支，發(fā)送到 master 分支的提交會被自動關(guān)閉。如果你的提交中包含多處修改，請將每一個修改都放到你獨(dú)立的分支中。

一次只做一件事：一個 pull request 應(yīng)該只包含一個修改。這不是意味著說一次提交，而是一次修改（盡管大多數(shù)時候 一次提交就是一次修改）。這樣做的原因是如果你在同一個 pull request 中修改了 X 和 Y ，但是我們希望能合并 X 同時不想合并 Y ，這時我們就無法合并你的請求。你可以使用 Git-Flow 分支模型為每一個功能創(chuàng)建一個獨(dú)立的分支， 然后提交兩個請求。

簽名

你必須對你的工作進(jìn)行簽名，保證這些工作是你原創(chuàng)的或者不是你原創(chuàng)的但是你有將它們添加到開源項(xiàng)目中的權(quán)利。 在 Git 中簽名并沒有得到足夠重視，所以你幾乎用不到?--signoff?參數(shù)，但是在你提交代碼到 CodeIgniter 時， 必須使用該參數(shù)。

git commit --signoff

或簡寫：

git commit -s

這個命令會根據(jù)你 git 的配置信息在你的提交中添加簽名，例如：

Signed-off-by: John Q Public .public@example.com](mailto:john.public%40example.com)>

如果你正在使用 Tower 客戶端，在提交窗口中會有一個 "Sign-Off" 復(fù)選框，或者你可以將?git?commit?設(shè)置成?git?commit?-s?的別名，這樣你就不用關(guān)心提交中的簽名了。

通過這種方式對你的工作進(jìn)行簽名，說明你將遵守 DCO （Developer's Certificate or Origin），Developer's Certificate of Origin 1.1?申明的當(dāng)前版本位于這份文檔的根目錄下。