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

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

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

CodeIgniter 是一個(gè)社區(qū)驅(qū)動(dòng)的項(xiàng)目，它會(huì)接受從社區(qū)里貢獻(xiàn)的文檔和代碼。 這些貢獻(xiàn)都是通過(guò) GitHub 上?CodeIgniter 代碼倉(cāng)庫(kù)?的 Issues 或者?Pull Requests?的形式來(lái)完成的。

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

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

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

支持

請(qǐng)注意，GitHub 并不是用來(lái)回答一般的技術(shù)支持類問(wèn)題的！

如果你在使用 CodeIgniter 的某個(gè)功能時(shí)遇到了問(wèn)題，請(qǐng)到論壇提問(wèn)。

如果你不知道自己做的對(duì)不對(duì)，或者不確定自己找到了一個(gè) bug ，也請(qǐng)先到論壇里提問(wèn)。

提交好問(wèn)題的技巧

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

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

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

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

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

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

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

指導(dǎo)手冊(cè)

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

PHP 代碼規(guī)范

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

文檔

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

兼容性

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

分支

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

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

簽名

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

git commit --signoff

或簡(jiǎn)寫：

git commit -s

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

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

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

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