Pull Request指南
Mod是在Forge之上诞生的,但Forge仍然还不支持一些东西,并且会限制Mod能够做的事情。每当Mod作者遇到这样的事情时,它们就可以对Forge进行改动来支持,并通过Pull Request将变动提交到GitHub。
为了节约你和Forge团队的时间,我们建议您在准备Pull Request时遵循一些基本的规则。如果想要写一个好的Pull Request的话,下面这些点都是非常重要的。
什么是Forge?
从整体来说,Forge是在Minecraft之上的一个Mod兼容层。
早期的Mod会直接修改Minecraft的代码(和现在的Coremod一样),但是在它们修改相同的东西时,就会遇到冲突。在一个Mod修改了一些不能预料到的行为的时候(和现在的Coremod一样),也会造成很奇怪的问题。
通过使用像Forge这样的东西,Mod就能中心化常见的变动并避免冲突了。
Forge也为了一些常用的Mod功能加入了一些辅助结构,包括能力、注册表、流体处理和矿物词典等来让Mod能更好在一起工作的东西。
当写作一个优秀的Forge Pull Request的时候,你还需要知道Forge在更低的层次上是什么。
Forge中主要有两种代码:Minecraft补丁和Forge代码。
补丁
补丁在应用后会直接修改Minecraft的源码,它应当是越少越好。
每当Minecraft代码有改动的时候,Forge所有的补丁都会被仔细检查修改,并正确应用到新的代码上。
这就意味着改动了很多东西的大补丁将会很难去维护,所以Forge希望尽可能的将补丁做得越小越好。
除此了让代码易于理解之外,补丁的审查将会注重于减少它的大小。
有很多技巧能够帮助你制作一个较小的补丁,审查过程中也经常会有人指出完成一个目标的更简单方式。
Forge的补丁通常会插入一行代码,触发一个事件或者一个代码钩子(Hook),如果事件满足一些条件的话,它将会影响之后的代码。
这将允许大部分的代码都处于补丁之外,保证了补丁的简洁。
如果你想知道更多关于创建补丁的信息,见GitHub Wiki。
Forge代码
除了补丁之外,Forge代码就是普通的Java代码。它可能是事件代码、兼容特性或其它不会直接修改Minecraft的代码。
当Minecraft更新的时候,和其它东西一样,Forge代码也需要更新。然而,它会更简单一些,因为它没有直接混杂在Minecraft代码之中。
因为这些代码是独立的,它没有补丁一样的大小限制。
除了要让代码易于理解,代码的审查通常会关注于让代码更干净,使用正确的格式和Java文档。
解释你的目的
所有的Pull Request都需要回答一个问题:为什么它是必须的?
向Forge加入的任何代码都必须要进行维护,更多的代码意味着Bug产生的可能性更大,所以加入新的代码都必须有合适的理由。
Pull Request的一个常见的问题是,没有提供任何的解释,或者提供了很奇怪的演示例子。
这样只会拖延Pull Request的过程。
对于通常情况的清晰解释是很有帮助的,但请还要给一个充分的例子,展示你的Mod为什么需要这个Pull Request。
为了达成你的目标,有时候会有更好的办法,或者是根本不需要Pull Request的办法。只有当这些可能性都被排除之后,代码的改动才能被接受。
展示它能正常工作
你提交给Forge的代码应该能正常工作,而说服审查者的工作在你的身上。
最好的方式就是添加一个范例Mod或者JUnit测试到Forge中,使用你的新代码,并且展示它们是如何工作的。
如果想要配置并运行一个包含范例Mod的Forge环境,请参考这篇指南。
对Forge的重大改动
Forge不能在作出改变之后让已有的Mod不能正常工作。
这就意味着Pull Request必须要保证它不能破坏与之前Forge版本的二进制兼容性(Binary Compatibility)。
破坏了二进制兼容性的改动将称之为重大改动(Breaking Change)。
对这一规则仍有一些例外,Forge在新Minecraft版本的初期会接受重大改动,Minecraft本身就已经对Mod作者产生重大改动了。
在这个时间段之外,有些时候紧急的重大改动也是必须的,这是非常不常见的,而且它可能会对Minecraft Mod社区中的每个人都造成麻烦。
除了这些例外时期,拥有重大改动的Pull Request都将不被接受,它们必须要进行修改以适配旧的版本,或者等待下个Minecraft版本的到来。
耐心、文明、有同情心
当提交Pull Request的时候,你需要熬过代码审查,作出一些改动,直到它是最完美的状态。请记住,代码审查并不是针对你的判断。你代码中的Bug并不是个人的错误。没有人是完美的,所以我们需要合作。
负面情绪是不会有任何帮助的,威胁要放弃你的Pull Request转而去写Coremod只会让人感到失望,让整个Mod生态系统更糟。
合作的时候很重要的是,要假设审查Pull Request的人是有好的意图的,不要感情用事。
审查
如果你能尽最大努力理解Pull Request过程中的缓慢和完美主义,我们也会尽力理解你的观点。
在你的Pull Request尽所有人的努力审查并清理之后,它将会被标记,留给Lex进行最终的审核,他会决定这个Pull Request是否会包含在工程中。