重症监护病房4X
是一个开源项目,欢迎大家参与。
核心团队已经确定了良好的初始项目,并为其提供了良好的首次发行标签。这是一个开始成为志愿者的好地方。
为了提供有意义的贡献,熟悉一组描述结构和样式指南由项目使用。
每个人都可以讨论问题,并且可以用于跳转项目的Pull Request。
在大多数情况下,第一步是找到或提交与您计划的贡献相关的新问题,进行讨论,一旦您收到反馈,表示欢迎撤回请求,您就可以开始处理了。
要构建ICU4X,您需要以下依赖项:
- 安装了铁锈(和货物)通过
生锈
货物制造
通过安装货物安装货物制造
货物-码头
通过安装货物安装货物仓库
某些测试可能需要进一步的依赖性,这些依赖性在下面的测试第节。
可以使用任何能够编辑Rust代码的文本编辑器编辑ICU4X。
许多ICU4X工程师使用Visual Studio代码使用锈蚀分析仪扩展。
为了构建所有代码路径,改进VSCode中的构建时间,并防止从命令行构建中锁定目标目录,我们建议使用以下设置。要添加它们,请从命令调色板中选择“首选项:打开工作区设置(JSON)”(Ctrl+Shift+P):
“设置”: {“锈迹分析仪。货物。特征”以下为:"全部的",“锈蚀分析仪.货物.外部环境”: {“CARGO_TARGET_DIR”以下为:"${workspaceFolder}/target/vscode",“ICU4X_DATA_DIR”以下为:"../../../datagen/测试/数据/烘焙"}}
注:中的路径ICU4X_DATA_DIR病房
相对于provider/baked/*/src/lib.rs
它导致VSCode只使用und(单位)
语言环境。这减少了构建时间,但也会导致一些测试失败;要正常运行,请运行货物试验所有特性
在命令行上。
第一步是将存储库分叉到您的命名空间,并创建主要的
要使用的分支。
该分支可能最终包含构成拉请求完整范围的一个或多个提交。
考虑捐款时,我们使用以下经验法则:中的所有代码组件/
,飞行情报员/
,提供者/
、和实用程序/
上主要的
分支必须随时准备发布。
实际上,这意味着在满足所有代码质量要求之前,不应合并新组件或现有组件的改进(请参阅下面的检查表)。
如果使用新组件,请在组件/实验
机箱。我们允许对该板条箱进行贡献,即使它们还不能满足我们所有的代码质量要求。完成后,代码可以作为单独的拉请求移动到自己的板条箱中。
如果要对现有组件进行改进,并将其拆分为多个较小的部分,请考虑将其隐藏在“实验性”
板条箱中的功能。这样做会向用户和工具发出一个信号,即代码尚未生产就绪。完成后“实验性”
特征可以从板条箱中删除。
在向main添加非外围代码时,还要更新changelog的“未发布”部分。这简化了发布,使我们能够更好地了解我们有哪些未发布的功能。
请注意,实际的Cargo.toml版本碰撞将在发布时完成,并且板条箱位于实用程序/
可能遵循与其他目录树下不同的发布节奏。
每个提交和拉请求都应遵循样式指南并使用正确的格式货物fmt
。如果公关部添加了任何公共API更改,我们还希望确保货运单据
保留,代码覆盖率高于90%
。
方便的命令(从根目录运行):
货物整洁
运行tidy-checks(许可证、fmt、自述文件)
快速货运
运行最快的测试和lint。
请参阅测试有关各种可用测试套件的更多信息,请参阅下面的部分。
在ICU4X存储库中有各种自动生成的文件。下面是一些您可以使用的命令需要运行才能重新创建它们。这些文件可以在更全面的测试中运行,例如货物制造ci-job-test
或货物制造ci-all
。
货物制造测试数据
-重新生成中的所有测试数据提供者/测试数据
目录。
货物制造生成自述文件
-根据Rust文档生成README文件。输出文件必须在git中提交才能通过检查。
货代外交官
-在中重新创建外交官生成的文件消防设施/消防设施
目录。
建议运行货物试验所有特性
在板条箱中,您正在进行修改,以确保没有任何损坏,并且快速货运
进行合理的检查,以确保所有内容仍在构建,并且lint检查通过。
我们更广泛的测试套件组织为ci-job-foo公司
使任务对应于每个GitHub Actions CI作业,您可以运行任何您认为相关的套件货物制造ci-job-foo
,或所有与ci-all公司
(这需要相当长的时间,最好让CI并行运行)。
ci-job-fmt公司
:跑步次数货物fmt
ci-job-tidy公司
:检查代码是否具有适当的许可标头和文件,以及README是否同步。
ci-job-fmt公司
和ci-job-tidy公司
可以一起运行货物整洁
。
ci-job-clippy公司
:跑步次数货夹——所有目标——所有功能
在所有的板条箱上。
ci-job-msrv检查
:跑步次数货物检查
所有板条箱上的最小支持锈蚀版本(MSRV)。
ci-job-msrv功能
:运行货物检查所有功能
在我们MSRV的所有板条箱上。这将检查所有功能组合,这相当慢。
ci-工作测试
:跑步次数货物试验
在所有的板条箱上。这需要一段时间,但这是确保没有任何损坏的主要方法。
ci-job-doc公司
:构建所有Rustdoc;任何警告都被视为错误。
ci-job-test-docs公司
:跑步次数货物试验文件
在所有的板条箱上。这需要一段时间,但这是确保没有任何损坏的主要方法。
ci-job-test-tutorials公司
:根据两个本地代码构建所有教程(区域设置
),并发布ICU4X(克拉齐奥
)。
ci-job-test数据
:运行icu数据源
利用CLDR、ICU和LSTM源数据子集进行集成测试。
ci-job-testdata-legacy公司
:为弃用的生成数据icu_测试数据
机箱。
ci作业完整数据生成
:生成所有板条箱的编译数据。
ci-job-test-c
:运行所有C/C++FFI测试;如果您要更改FFI接口,最重要的是。
- 要求
叮当声-16
和lld-16号机组
使用金
插件(APT包llvm-16型
和lld-16号机组
)。
ci-job-test-js
:运行所有JS/WASM/Node FFI测试;如果您正在更改外国金融机构接口,这一点非常重要。
- 需要Node.js版本16.18.0。这可能不是包管理器提供的;从NodeJS网站获取,或
非挥发性物质
。
ci-job-nostd公司
:为#[编号]
以验证其兼容性。
ci-job-diplomat公司
:验证外交官生成的绑定是否是最新的。
ci-job-gn公司
:验证GN包装是否为最新。
Pull Request生命周期分为两个阶段。
第一个是完成Pull Request以备审查的工作。另一个是审查周期。
如果pull请求简单且生存期短,则可以使用review请求对其进行初始化。如果拉取请求更复杂,并且随着时间的推移正在开发,那么在草稿
状态。这允许其他贡献者监视进度和志愿者反馈,同时说明拉取请求尚未准备好进行审查。
如果一个拉请求的范围特别大,并且还没有发布,那么可以考虑(1)缩小拉请求的作用域,(2)将工作转移到icu_实验
板条箱,或(3)将工作隐藏在“实验性”
功能标志。有关更多详细信息,请参阅上面的“发布就绪”部分。
在这个阶段结束时,就在请求审查之前,审查人员在拉请求中有一个干净的提交列表是很有帮助的。
在大多数情况下,每个拉请求一次提交就足够了。
当提交过大时,应使用多次提交,并且可以通过将其分为多个逻辑上独立的提交来减少更改范围。与一次审阅所有更改相比,这样的提交不必单独通过测试,只需要有意义地完成,以便审阅者从阅读中受益。
一旦拉取请求准备好进行审查并通过所有测试,作者就可以从草稿切换到常规拉取请求。
此时,将在下一次分类会话中对拉请求进行分类,并为其分配审阅者。拉请求作者还可以请求特定个人进行审阅。在这样做时,鼓励向这些评审员传达所需的评审重点。
在这个阶段,应用于拉请求的任何更改都应该导致对它的附加提交。这允许审阅者查看他们的反馈所做的更改并对其进行评估。
每个公关都需要至少一次审查才能合并。
如果作者拥有对存储库的编辑权限,则应由拉取请求的作者执行合并。如果作者想授予另一个团队成员合并的权限,他们可以在公关评论中声明。
如果拉动请求修改了其中一个已识别组件中的代码,那么其中一个组件所有者应该位于拉动请求的审阅者列表中。有关组件及其所有者的列表,请参见代码所有者。
如果请求的作者至少有一个审批人,并且认为请求得到了充分的审查,那么他应该可以自由地删除待定的审查人。
如果在批准审核后进行了微小更改,则审核人显然不会在意(例如申请货物fmt
,或解决次要的剩余评审意见),可以要求其他维护人员对Slack或其他地方进行“橡皮图章”评审,作为GitHub的一个变通方法,不允许维护人员自行批准。
每个项目都有自己的代码编写和审查文化,随着项目的成熟,这些文化会有机地增长,并且会发生变化。下面是我们试图遵循的模型的描述,但常识另有规定的情况除外。
审查可以是建筑的或技术的价值,通常两者兼而有之。
公关作者可以在请求审阅时指定他们要从每个审阅者那里获得什么样的审阅,甚至可以指定他们希望审阅者关注的领域(在分发审阅时很有用)。
评审员只有在认为当前的公关已经准备好合并时才负责接受拉取请求,即使他们的评论没有被应用。
这个批准如果这些评论不影响补丁是否可以合并(例如,它们是风格建议),则可以设置待定的评论。
我们尝试使用常规评论对于评论,明确标记每个评论的权重和阻塞性质。
重症监护病房4X
project专注于一个相当封闭的软件国际化领域,这需要对该领域有先验知识。考虑到这一点,大多数从事补丁编写和审查的工程师都应该具有足够的资历,可以信任他们对代码的添加质量。
出于这些原因,我们主要将信任inpull要求作者编写高质量、可读、测试、可维护且文档化良好的代码。
The role of the评审员在这种模型中更为保守,简化为从特定角度验证代码,对pull请求的影响最小。此类角度的示例可以是:
- 公关如何融入组件的公共API
- 公关与项目目标和范围的一致性
- 拉入请求中代码的内存管理
- 测试覆盖率和健全性检查
- 使用CLDR、Unicode、Rust和其他最佳实践
- 与ICU4X的一致性样式指南
- I/O、数据管理等的使用。
pull请求作者需要评估他们需要什么样的审查来确保pull请求的质量。
评审员的一个重要角色是正确使用三种类型的评审意见(必需、建议或可选)。
最后,评审员的职责是评估利益相关者群体,并确保评审覆盖范围是完整的——如果他们只评审了PR的一部分,或者如果他们认为需要更多的利益相关者参与,他们应该增加更多的评审员,或者将他们纳入问题中,取决于他们期望的参与方式(告知vs核实)。
上面列出的方法描述了我们基于对贡献者群体组成的假设而追求的文化,当拉式请求作者是该领域的新手且不具备领域专业知识时,应进行调整。在这种情况下,导师制模式应在更高级的工程师担任导师的情况下使用。
当公关作者创建新的公关时,他们应该考虑三个审查人员来源和知情的利益相关者:
- 与他们一起工作的组件的所有者和同行
- 参与前一次对话的人员
- 公关领域公认的专家
公关作者的目标是找到代表这三个群体的利益相关者子集。根据公关的范围和优先级,可以调整评论员组的规模,小的公关足以由一个利益相关者进行审查,大的公关,或者使用更大的评论员库进行第一次审查。
当作者提交PR供审阅时,GitHub将自动分配一个或多个可以审阅它的代码所有者。作者有责任从此列表中选择一个或两个审阅者,并删除其他审阅者。如果公关规模大、复杂或有争议,可以添加更多评论员。通常最好保持所需的审阅者列表较小。从PR中删除的审阅者如果有兴趣进行审阅,可以重新添加自己。
在一轮审查之后,如果存在阻碍问题,作者必须更新所有阻碍审查者的公关和重新请求审查。PR不得与待审核合并。如果公关作者决定做出任何超出审查人员批准范围的实质性更改,他们可以在更新公关后重新请求已经接受的审查。
以下PR有一个非阻止审查、两个批准和两个待定审查。作者应等待来自埃文JP和nciric公司合并之前。
以下PR有两个非阻止审查和一个批准。由于没有待定的评论,作者可能会合并此PR。
以下PR有一个非阻止性审查、一个阻止性审查,一个批准和一个待定审查。作者应等待sffc解决其阻塞审查,并等待nciric在合并之前留下审查。
注:当新的提交被推送到分支时,GitHub将审批转化为非阻塞审查。
为了对该项目作出贡献,Unicode联盟必须存档一份贡献者许可协议(CLA),涵盖您的贡献,无论是个人还是公司CLA。在签署正确的CLA之前,不会合并/接受Pull请求、问题和其他贡献。需要签署哪一个版本取决于谁拥有所做的贡献:你是做出贡献的个人还是你的雇主。您有责任确定您的供款是否由您的雇主所有。请查看Unicode知识产权、许可和技术贡献政策有关签署CLA的进一步指导,以及有关联合体许可和技术贡献政策和程序的其他信息和指南。
要在Github中签署CLA,请打开一个Pull Request(将自动添加一条评论,并链接到CLA Form),或直接转到CLA表格。您可能需要登录Github才能查看整个CLA表格。
除非在许可证文件,此项目在OSI批准免费开源Unicode许可证v3。
添加新的Rust文件时,请确保以以下精确文本开头:
//此文件是ICU4X的一部分。有关使用条款,请参阅文件//在ICU4X源代码树的顶层调用了LICENSE//(在线:https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
添加新的TOML文件时,请确保它以以下精确文本开头:
#此文件是ICU4X的一部分。有关使用条款,请参阅文件#在ICU4X源树的顶层称为LICENSE#(在线:https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
对于支持注释的非Rust/TOML文件,请根据文件格式和用例的实际情况,在文件顶部附近使用适用文件格式的注释语法,为上述内容添加注释。
导入预先存在的代码时,请注意以下几点:
当导入具有预先存在的许可证标头的现有(Apache-2.0或MIT)许可代码时,请在预先存在的许可证标头上添加以下内容(替换CRATE_名称
原始板条箱名称):
//以下代码是从CRATE_NAME导入的,其中包含//以下通知(文件位置已被文件取代//在ICU4X源树的顶层称为LICENSE):
(后面是Rust文件的原始Apache-2.0 OR MIT许可样板)
另外,在每个Rust源文件的开头添加“新文件”部分的文本。
将传入的MIT许可证版权声明从导入的代码复制到顶级license文件中。
使用许可证文件
键入货物.toml
请参阅许可证文件。
从ICU4C或ICU4J移植代码时,在源代码注释中使用以下注释(替换重症监护病房4C
具有重症监护病房4J
(如适用):
//以下代码以ICU4C的端口开始,该端口携带//以下通知:
(遵循ICU4C/ICU4J源文件中的原始样板)
另外,在每个Rust源文件的开头添加“新文件”部分的文本。
如果您的端口代码在第三方许可在ICU4C/J中,自ICU4C许可证文件的链接修订版起,如果其许可证尚未包含在ICU4 X许可证文件中,请在许可证文件例外列表中添加有关代码部分和第三方许可证的注释,包括许可证文件末尾的第三方许可证以及许可证的标题,并且在代码中使用注释来指示代码在特定的第三方许可下。
当Rust文件中包含的表是从Unicode数据生成的时,请让生成器在表上方生成此注释:
//以下表格是根据包含以下内容的Unicode数据生成的//以下通知:
(后面是Unicode数据的原始样板文件)
请先讨论。