开发者指南和编码风格

请先阅读新开发者指南 。

基本准则和编码风格

对于任何在开源项目或商业编程环境中工作过的人来说,以下大部分内容应该是常识。以下内容主要适用于主开发分支 i2p.i2p。其他分支、插件和外部应用的指南可能会有很大差异;请咨询相应的开发人员以获取指导。

社区

• 请不要只是编写代码。如果可以的话,请参与其他开发活动,包括:在 IRC 和 i2pforum.i2p 上的开发讨论和支持;测试;错误报告和响应;文档编写;代码审查等。
• 活跃的开发者应该定期在 IRC #i2p-dev 上保持可联系。了解当前的发布周期。遵守发布里程碑,如功能冻结、标签冻结以及发布的代码提交截止日期。

发布周期

正常的发布周期为10-16周，每年四次发布。以下是典型13周周期内的大致截止日期。每次发布的实际截止日期由发布管理员在与整个团队协商后确定。

• 上一版本发布后 1-2 天:允许向主干提交代码。
• 上一版本发布后 2-3 周:将其他分支的主要更改合并到主干的截止日期。
• 发布前 4-5 周:请求新主页链接的截止日期。
• 发布前 3-4 周:功能冻结。主要新功能的截止日期。
• 发布前 2-3 周:召开项目会议审查新主页链接请求(如有)。
• 发布前 10-14 天:字符串冻结。不再更改已翻译(已标记)的字符串。将字符串推送到 Transifex,在 Transifex 上公告翻译截止日期。
• 发布前 10-14 天:功能截止日期。此后仅允许错误修复。不再添加功能、重构或清理代码。
• 发布前 3-4 天:翻译截止日期。从 Transifex 拉取翻译并提交。
• 发布前 3-4 天:提交截止日期。此后未经发布构建者许可不得提交代码。
• 发布前数小时:代码审查截止日期。

Git

• 对分布式源代码控制系统有基本了解,即使你之前没有使用过 git。如果需要帮助请提出。一旦推送,提交就是永久性的;没有撤销操作。请务必小心。如果你之前没有使用过 git,请从小步骤开始。提交一些小的更改,看看效果如何。
• 在提交更改之前测试你的更改。如果你更喜欢先提交后测试的开发模式,请在你自己账户中使用你自己的开发分支,并在工作完成后创建一个 MR(合并请求)。不要破坏构建。不要造成回归问题。如果你确实造成了问题(这种情况会发生),请不要在推送更改后长时间消失。
• 如果你的更改不是微不足道的,或者你希望人们测试它并需要良好的测试报告来了解你的更改是否经过测试,请在 history.txt 中添加一个提交注释,并在 RouterVersion.java 中增加构建修订版本号。
• 不要在发布周期后期将重大更改提交到主 i2p.i2p 分支中。如果一个项目需要你花费超过几天时间,请在 git 中你自己的账户里创建你自己的分支,并在那里进行开发,这样你就不会阻碍发布。
• 对于大的更改(一般来说,超过 100 行,或涉及超过三个文件),将其提交到你自己 GitLab 账户上的新分支中,创建一个 MR,并指定一个审查者。将 MR 分配给你自己。一旦审查者批准,由你自己合并 MR。
• 不要在主 I2P_Developers 账户中创建 WIP(进行中的工作)分支(除了 i2p.www)。WIP 应该在你自己的账户中。当工作完成后,创建一个 MR。主账户中的分支应该仅用于真正的分叉,比如点发布版本。
• 以透明的方式进行开发,并考虑到社区。经常提交。在遵循上述准则的前提下,尽可能频繁地提交或合并到主分支。如果你正在自己的分支/账户中进行某个大项目,请让人们知道,以便他们可以跟进并审查/测试/评论。

编码风格

• 大部分代码的编码风格是使用 4 个空格缩进。不要使用制表符。不要重新格式化代码。如果你的 IDE 或编辑器想要重新格式化所有内容,请控制好它。在某些地方,编码风格有所不同。使用常识。模仿你正在修改的文件中的风格。
• 所有新的公共和包私有类和方法都需要 Javadocs。添加 @since 版本号。新私有方法的 Javadocs 也是需要的。
• 对于添加的任何 Javadocs,不得出现任何 doclint 错误或警告。使用 Oracle Java 14 或更高版本运行 ant javadoc 进行检查。所有参数必须有 @param 行,所有非 void 方法必须有 @return 行,所有声明抛出的异常必须有 @throws 行,并且不能有 HTML 错误。
• core/(i2p.jar)中的类和 i2ptunnel 的部分内容是我们官方 API 的一部分。有几个树外插件和其他应用程序依赖于此 API。小心不要做出任何破坏兼容性的更改。除非具有通用实用性,否则不要向 API 添加方法。API 方法的 Javadocs 应该清晰完整。如果你添加或更改 API,还要更新网站上的文档(i2p.www 分支)。
• 在适当的地方标记字符串以供翻译,所有 UI 字符串都需要这样做。除非确实必要,否则不要更改现有的已标记字符串,因为这会破坏现有的翻译。在发布周期的标签冻结后,不要添加或更改已标记的字符串,以便翻译人员有机会在发布前进行更新。
• 尽可能使用泛型和并发类。I2P 是一个高度多线程的应用程序。
• 熟悉 FindBugs/SpotBugs 捕获的常见 Java 陷阱。运行 ant findbugs 了解更多信息。
• 从 0.9.47 版本开始,构建和运行 I2P 需要 Java 8。不要在嵌入式子系统中使用 Java 7 或 8 的类或方法:addressbook、core、i2ptunnel.jar(非 UI)、mstreaming、router、routerconsole(仅 news)、streaming。这些子系统被 Android 和仅需要 Java 6 的嵌入式应用程序使用。所有类必须在 Android API 14 中可用。如果当前版本的 Android SDK 支持并且它们编译为 Java 6 兼容的代码,则这些子系统中可以使用 Java 7 语言特性。
• Try-with-resources 不能在嵌入式子系统中使用,因为它需要运行时的 java.lang.AutoCloseable,而这直到 Android API 19(KitKat 4.4)才可用。
• java.nio.file 包不能在嵌入式子系统中使用,因为它直到 Android API 26(Oreo 8)才可用。
• 除上述限制外,Java 8 的类、方法和构造仅可在以下子系统中使用:BOB、desktopgui、i2psnark、i2ptunnel.war(UI)、jetty-i2p.jar、jsonrpc、routerconsole(除 news 外)、SAM、susidns、susimail、systray。
• 插件作者可以通过 plugin.config 文件要求任何最低 Java 版本。
• 在原始类型和类之间显式转换;不要依赖自动装箱/拆箱。
• 不要使用 URL。使用 URI。
• 不要捕获 Exception。单独捕获 RuntimeException 和已检查异常。
• 不要在没有 UTF-8 字符集参数的情况下使用 String.getBytes()。你也可以使用 DataHelper.getUTF8() 或 DataHelper.getASCII()。
• 读取或写入文件时始终指定 UTF-8 字符集。DataHelper 实用程序可能会有所帮助。
• 使用 String.toLowerCase() 或 String.toUpperCase() 时始终指定区域设置(例如 Locale.US)。不要使用 String.equalsIgnoreCase(),因为无法指定区域设置。
• 不要使用 String.split()。使用 DataHelper.split()。
• 不要添加格式化日期和时间的代码。使用 DataHelper.formatDate() 和 DataHelper.formatTime()。
• 确保在 finally 块中关闭 InputStream 和 OutputStream。
• 对所有 for 和 while 块使用 {},即使只有一行。如果你对 if、else 或 if-else 块中的任何一个使用 {},则对所有块都使用它。将 } else { 放在单独一行上。
• 尽可能将字段指定为 final。
• 不要在静态字段中存储 I2PAppContext、RouterContext、Log 或对 router 或 context 项的任何其他引用。
• 不要在构造函数中启动线程。使用 I2PAppThread 而不是 Thread。

日志记录

以下准则适用于 router、webapps 和所有插件。

• 对于任何不在默认日志级别（WARN、INFO 和 DEBUG）显示的消息，除非消息是静态字符串（无拼接），否则始终在日志调用前使用 log.shouldWarn()、log.shouldInfo() 或 log.shouldDebug()，以避免不必要的对象创建开销。
• 可能在默认日志级别（ERROR、CRIT 和 logAlways()）显示的日志消息应该简洁、清晰，并且易于非技术用户理解。这包括可能同时显示的异常原因文本。如果错误可能发生（例如，在表单提交错误时），请考虑翻译。否则，翻译不是必需的，但搜索并重用其他地方已标记为翻译的字符串可能会有所帮助。
• 不在默认日志级别（WARN、INFO 和 DEBUG）显示的日志消息是供开发人员使用的，不需要满足上述要求。但是，WARN 消息在 Android 日志选项卡中可用，可能有助于用户调试问题，因此也要谨慎使用 WARN 消息。
• INFO 和 DEBUG 日志消息应谨慎使用，特别是在热代码路径（频繁执行的代码）中。虽然在开发期间很有用，但在测试完成后请考虑删除或注释掉它们。
• 不要记录到 stdout 或 stderr（wrapper log，包装器日志）。

许可证

• 仅提交你自己编写的代码。在提交任何来自其他来源的代码或库 JAR 文件之前,请说明为何必要,验证许可证是否兼容,并获得发布管理者的批准。
• 如果你确实获得批准添加外部代码或 JAR 文件,并且在任何 Debian 或 Ubuntu 软件包中有可用的二进制文件,你必须实现构建和打包选项以使用外部软件包。需要修改的文件清单:build.properties、build.xml、debian/control、debian/i2p-router.install、debian/i2p-router.links、debian/rules、sub-build.xml。
• 对于从外部来源提交的任何图像,你有责任首先验证许可证是否兼容。在提交注释中包含许可证和来源信息。

错误

• 管理问题是每个人的工作；请提供帮助。关注 GitLab 上您可以提供帮助的问题。如果可以，请对问题进行评论、修复和关闭。
• 新开发者应该从修复问题开始。当您有了修复方案时，将补丁附加到问题上并添加关键词 review-needed。在成功审查并检入更改之前，不要关闭问题。一旦您顺利完成几个工单的处理后，就可以遵循上述正常流程。
• 当您认为已经修复问题时就关闭它。我们没有测试部门来验证和关闭工单。如果您不确定是否已修复，请关闭它并添加注释说明"我认为已经修复，如果仍然存在问题请测试并重新打开"。添加包含开发版本号或修订版本的评论，并将里程碑设置为下一个发布版本。