铁匠(程序员)对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的管理员推荐这些学习资源:
|
测试[]
技术 | 更多信息 |
---|---|
Mocha |
逆向工程需求文档[]
2019年6月,Brasília大学的学生为了一个项目分析了Habitica。他们的目标是逆向工程Habitica的网站,以开发需求工件。这个部分显示了两个他们开发的丰富图(Rich Picture)。丰富图是一种探索情景并以图表表达之,显示其流程的方式。虽然这些图片不是官方的Habitica文档,但是它们可以帮助新的代码贡献者理解这个站点,并帮助开发特性和修复bug。点击每个图片查看放大版。
这些图片来自他们的Wiki项目 https://requisitos-habitica.netlify.com 。
在本地运行环境中工作[]
铁匠应该创建一个本地运行的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)