鐵匠

鐵匠（程式設計師）對Habitica的成功來說至關重要。我們需要和感激您的貢獻！有好幾種方式可以使用您的編程技能為網頁版和行動應用程式做出貢獻。要想了解可以做些什麼，重要的第一步是閱讀本頁面和本頁面連結到的頁面，然後加入Aspiring Blacksmiths (Habitica Coders)公會詢問任何你可能想知道的問題。

如果你想為Habitica的網站或者API貢獻代碼，也一定要閱讀本地搭建Habitica獲取關於準備開始的重要信息，然後閱讀使用您的本地安裝來修改Habitica的網站和API學習更改代碼的過程。

提供幫助的方式[]

網頁端[]

要協助網站或者API的建設，你可以在Habitica的工作人員的同意之後修復bug或者添加特性。Bug和特性都在GitHub倉庫中公告，並帶有「help wanted」標籤。

強烈建議先閱讀GitHub標籤頁面之後再決定解決哪個issue，其中解釋了Habitica的標籤系統（例如如何找到簡單到中等難度的問題，或者你感興趣的問題）並且帶有指向按每個標籤分類的issue的連結。

在開始解決bug或者添加特性之前：

確保這個issue有「help wanted」標籤。沒有這個標籤的issue要麼是有人在做了，要么正在懸置，或者由於其他原因不適合由貢獻者解決。（如果你認為某個不帶這個標籤的issue適合你，你也可以按照下文詢問，但是一定要等到有人回復才開始碼代碼！）
閱讀issue的描述和所有評論，確保自己理解這個問題和需要的修復或者特性。
看看最新的評論，如果另一位鐵匠已經請求著手解決它，那就留給ta做。
在issue下發表評論，聲明你想要解決它。
- 根據具體的問題，你可能想要描述你建議的方案，讓管理員們（工作人員和版主）討論其可行性。如果你不知道要不要說，那就不用；如果想知道，管理員們會問的。
等一位管理員來同意你開始工作。有時即使「help wanted」issue也不適合修復（例如它已經修好了但是忘記改標籤和關issue），所以等一個同意可以避免你浪費寫碼時間！
如果你在發評論請求解決issue三到四天之後還沒有收到回復，請再發一次！

請注意如果你在收到回復之前就開始動手解決issue，那麼如果這個issue已經不再適合修復，你的工作可能會白費。

針對網站和API代碼的測試[]

如使用您的本地安裝來修改Habitica的網站和API中所說，Habitica的網站和API代碼包含一個測試套件。

我們歡迎對這些測試的添加或者改進！如果你看到可以提高測試覆蓋面的地方，最好的方式是向admin@habitica.com寫一封郵件，描述你建議的改進（你可以在幫助 > 報告問題處這麼幹），並等管理員回復。他們會說你可以繼續干，或者創建Github issue進行更多討論。

iOS和安卓移動應用[]

為移動應用作出貢獻算入制箭者工作的範疇，儘管和這裡寫的鐵匠工作有些相似。要了解如何成為制箭者，請參見安卓和iOS的制箭者指南。

實現你自己的特性[]

如果你想到了一個還沒有GitHub issue的特性，請通過Habitica用戶反饋與建議表格提出建議，這個表格也可以從Habitica網站上幫助 > 請求新功能處，或者移動應用的菜單 > 幫助和FAQ 處找到。在你的請求中表明你是個程式設計師並且想要自己來實現這個特性。附上聯繫方式，等一位工作人員聯繫你並告知請求已通過。

請注意請求可能需要幾個月才能通過，因為工作人員需要統籌特性請求來保證網站和移動應用保持一致且易用。

聯繫方式可以是郵箱地址或者你的Habitica用戶ID。（你也可以寫上@Username 或者顯示名（暱稱），但是一定要有郵箱或者用戶ID，這樣即使你改名了，工作人員也可以聯繫到你。）

請注意如果你在得到同意之前實現特性，你的特性可能不會被接受，導致你的時間被浪費。儘管Habitica是開源的，工作人員也需要檢查所有特性，保證它們與現有特性和未來計劃相適應。

網站技術棧[]

Habitica網站所用的技術如下所示。你不需要熟悉所有的，甚至不需要熟悉大部分的，就能做出貢獻！一些高質量學習材料的連結也包括在內。這些技術(那些在名稱或者URL中帶有「.js」或'JS'的)中有許多是基於程式語言JavaScript，你可以在這裡學習。

服務端[]

技術	更多信息
ExpressJS
Node.js	我如何開始Node.js開發 nodeschool -- 一個特別有用的入門級互動Node課程。
MongoDB	官方MongoDB文檔查看下方MongoDB章節以獲得一些簡短的提示。
MongooseJS
Gulp	你可以在 Gulp GitHub 頁面了解相關信息
Git 和Github	Pro Git -- 花點時間閱讀這個極好的資源將幫助你更加熟悉Git。 git-it -- nodeschool 課程中的這一有趣的交互式的部分將有助於學習Git 和Github。(向下滾動查看更多信息。)
ESLint	HabitRPG項目的Eslint配置

客戶端[]

技術

更多信息

Bootstrap

SCSS (SASS)

Vue.js

Vue.js為站點提供響應式的前端。Habitica的管理員推薦這些學習資源：

https://vuejs.org/v2/guide/ - 最重要的參考
http://vuejs-templates.github.io/webpack/ 和 https://vue-loader.vuejs.org - 對理解搭建步驟非常有用
http://router.vuejs.org/en/ - 路由文檔；並不像其他的那樣重要，並且你可能大部分時間都不需要這些知識。
http://vuex.vuejs.org/en/intro.html - 狀態管理；只讀介紹部分，因為Habitica使用的代碼略有不同

測試[]

技術	更多信息
Mocha

逆向工程需求文檔[]

2019年6月，Brasília大學的學生為了一個項目分析了Habitica。他們的目標是逆向工程Habitica的網站，以開發需求工件。這個部分顯示了兩個他們開發的豐富圖（Rich Picture）。豐富圖是一種探索情景並以圖表表達之，顯示其流程的方式。雖然這些圖片不是官方的Habitica文檔，但是它們可以幫助新的代碼貢獻者理解這個站點，並幫助開發特性和修復bug。點擊每個圖片查看放大版。

這些圖片來自他們的Wiki項目 https://requisitos-habitica.netlify.com 。

RevEngReqmnts-RichPicture-General — Habitica的一般流程，以及Habitica如何利用遊戲化系統來解決工作時無聊的問題。

RevEngReqmnts-RichPicture-Inventory — Habitica的物品欄系統。

在本地運行環境中工作[]

鐵匠應該創建一個本地運行的Habitica實例，用於測試和開發。創建本地實例的過程可能比較困難，因此我們收集了每個作業系統的步驟：本地搭建Habitica。

使用本地安裝進行更改和pull requests的過程在使用您的本地安裝來修改Habitica的網站和API中有描述。

MongoDB[]

為學習如何使用MongoDB，我們建議閱讀官方MongoDB文檔或其他更可靠的線上資源，但是這裡有一些基本命令的示例，可以幫助新開發人員快速理解使用MongoDB。你可以在MongoDB命令行接口(CLI)或使用例如Robo 3T IDE'的GUI工具運行這些語句。

在下面的命令中, $ 符號代表著Unix, Windows或Git Shell提示符，> 符號代表著Mongo CLI shell提示符。只在你的命令行中鍵入 $ 或 > 後出現的文本。

以下是語句是訪問Mongo shell，然後選擇你本地安裝的Habitica資料庫：

   $ mongo
   > show dbs
   > use habitica-dev

或者，直接在啟動shell的時候指定資料庫：

   $ mongo habitica-dev

查看資料庫中的「集合」 ("users", "groups"等)：

   > show collections

查看「users」集合中一個用戶的完整「document」 (用戶的User ID為12345678-b5b9-4bb4-8b82-123456789abc)：

   > db.users.find({_id: '12345678-b5b9-4bb4-8b82-123456789abc'})[0]

只查看用戶文檔中的 preferences 對象：

   > db.users.find({_id: '12345678-b5b9-4bb4-8b82-123456789abc'})[0].preferences

使用帶有 $set的 update 方法為用戶更改一個值：

   > db.users.update({_id: '12345678-b5b9-4bb4-8b82-123456789abc'}, {$set: {'profile.name':'New Display Name'}})

Using Your Local Install to Modify Habitica's Website and API 提供了用於特定目標的高級示例，這些示例可能在測試你的代碼更改時會對你有用。

可翻譯字符串 (本地化文件)[]

可翻譯字符串出現在 website/common/locales/en 路徑下的文件中。每個字符串都由一個key和一段文字組成，例如：

   'clearAll': 'clear all items',

不要編輯 website/common/locales 下其他目錄中的文件，因為所有的翻譯都在Weblate中管理

你應該每次都在本地安裝中測試你對字符串的編輯和修改。永遠不要想當然地認為，即使是簡單的字符串添加操作也會像預期的那樣工作。

添加可翻譯字符串[]

當你添加會被玩家讀到的文本時，你應該把它做成可翻譯字符串，這樣所有語言的用戶都能受用。有一些罕見的例外（例如只會給用API的程式設計師看到的報錯信息），但是這樣的例外一般在你所要解決的issue中會有描述。

要添加新的可翻譯字符串，請在Vue或JavaScript文件中使用 t 函數將其寫入。例如:

   env.t("newKey")
   i18n.t('newKey')

為示例查找要修改的文件中的現有字符串。

然後，在 website/common/locales/en目錄下，編輯相應的json文件，添加新字符串如下:

       'newKey': 'String Title',

如果json文件中已經有關於相同主題的字符串，那麼最好將新字符串添加到與現有字符串相同的位置，以便保證類似的字符串能被放在一起。

如果沒有類似的字符串，則將你的字符串添加到文件的末尾。先將逗號添加到之前曾是文件中的最後一個字符串的末尾。不要在你添加的字符串後面加逗號。

修改可翻譯字符串[]

現有的字符串在必要時可以隨時更改。

除非有充分的理由，否則不要更換key。例如，如果你需要將字符串「'clear all items」（清除所有物品）更改為「delete all items」（刪除所有物品），你不用將其對應的key也從「clearAll」更改為「deleteAll」，因為原始key的含義仍然是準確的。

key通常不進行更改的原因是它們可以被Habitica代碼中的多個地方引用，所以一旦更改所有這些代碼片段都需要更新；除非有充分的理由，否則這是不可取的。此外，當一個key被更改，翻譯人員要在沒有原始翻譯可以作為對照的情況下重做翻譯。請注意，當有理由更改key時，仍然不應該為英語以外的語言修改locales目錄。

圖像[]

有關為Habitica創建新圖像的信息，請參見藝術家指南。

當圖像已經擬定好並且獲得了工作人員的批准後，一個issue將會被創建以用來請求將圖像添加到Habitica。
然後鐵匠需要將其添加到庫中。大部分圖像需要複製到 website/client/assets/路徑中合適的子目錄下。

在添加新圖像或現有圖像的新版本之後，運行 npm run sprites來重新編譯圖像的spritesheet。

有時，這個命令會導致創建一個新的spritesheet，在這種情況下使用git add來添加新文件。
你可以在 website/client/assets/images/sprites/和website/client/assets/css/sprites/下找到它們。

其他有用的命令[]

下面是各種有用的命令。

搜索代碼[]

你經常想要搜索所有包含一些關鍵字或字符串的文件，以確定在添加/編輯某些特性時需要編輯哪些文件。使用 grep 命令(在您的作業系統上搜索關於grep的信息)或 git grep命令(git文檔將教你如何使用它)。

偏好設置[]

Habitica為用戶提供了自定義網站行為的偏好設置。如果需要，可以添加新的設置。請不要添加只有一小部分用戶可能會使用的設置，或微不足道的個性化設置。相反，選擇一個大多數用戶可能喜歡的行為。過多的偏好設置會使設置屏幕看起來雜亂無章，並增加了外觀的複雜性。如果你不確定是否需要添加一個偏好設置，你可以在相關的GitHub issue或pull request中討論它

當有必要添加一個新的用戶偏好設置時，可以將其添加到website/server/models/user/下的文件中。通常，資料庫會自動獲取新設置並根據需要將其添加到用戶帳戶。如果需要手動修改資料庫，管理員可以這樣做。

「給開發者的信息」普通Wiki頁面上的部分[]

在一些wiki頁面的底部，有一些稱為給開發者的信息的部分。這些部分包含了與頁面內容相關的對鐵匠有用的提示。

信息隱藏在一個劇透樣式的顯示/隱藏切換按鈕後面，所以對於非技術用戶來說，這一部分不會使頁面變得混亂。

這些部分使用 {{InfoForDevs Start}} and {{InfoForDevs End}} 模板來確保按鈕和其他文本的格式的正確性。要查看這是如何實現的，請在原始碼編輯器中打開任何帶有給開發者的信息部分的頁面。

要查看此部分的所有頁面列表，請使用"What links here" 工具查看連結至 'Start' 模板的頁面.

要想默認不隱藏所有給開發者的信息部分：

創建一個Wikia帳戶，如果你還沒有的話。
編輯你的個人Wikia css文件，位於 http://habitica.fandom.com/zh/wiki/User:这里填写你的用户名/wikia.css
將這幾行添加到CSS文件中:

   /* 强制使所有"给开发者的信息" 区域一直可见 */
   .habitrpg-InfoForDevs {
       display:block !important;
   }
   .habitrpg-InfoForDevs-hideIfDev {
       display:none;
   }

在en:User:LadyAlys/wikia.css中你可以看到一個例子。

申請貢獻者等級[]

你很幸運！鐵匠不需要做任何特別的事情，比如完成一個貢獻者等級請求(就像抄寫員被要求做的那樣)，以獲得貢獻者等級。鐵匠的貢獻者等級將由管理員在審查和接受鐵匠的提交內容時授予。管理員將跟蹤記錄鐵匠的貢獻積分，以便未來對貢獻者等級升級。

鐵匠的前一個或兩個貢獻者等級非常容易獲得，你可能會發現完成一個pull request就足夠獲得它們了。更高的等級需要更多的工作，可能需要幾個成功的pull request。每一個pull request完成時管理員將進行記錄，當已經作出足夠的貢獻時會獎勵一個等級。

一般來說，當一個PR被合併時，管理員會在PR和Hall of Heroes里寫一些類似「我給了你x等級」（I've given you Tier x）或者「已記錄到你的下一個貢獻者等級中」（Noted toward your next contributor tier）之類的話。如果他們寫了一些類似於後者的東西，這意味著僅靠這一次的PR還不足以得到一個等級，或不足以提升你的等級至下一級，如果你已經有了其他一部分積分。如果管理員沒有對你的PR作出有關貢獻者等級積分的任何評論，請提出到PR中來詢問它！管理員有時確實會忘記，但他們總是喜歡溫和的提醒，因為對貢獻者的工作給予讚揚是很重要的。

另請參閱[]

本地搭建Habitica
使用您的本地安裝來修改Habitica的網站和API
應用程式接口
GitHub
- GitHub標籤
- BountySource
- 致命碎蟲錘
含有給開發者的信息的維基頁面（en）

鐵匠

目次