NSPR 贡献者指南¶

摘要

NSPR 接受来自多个来源的各种形式的贡献，包括错误修复、新功能、库、平台移植、文档、测试用例等。我们（NSPR 模块所有者）有时会让贡献者失望，因为我们必须拒绝他们的贡献。我们拒绝贡献的原因多种多样。其中一些原因对于外部观察者来说并不明显。NSPR 希望为那些有意向为 NSPR 做贡献的人提供一些指南。这些指南应该帮助贡献者设计他们的贡献，从而提高其被接受的可能性。

通用指南¶

向下兼容性¶

因为除了 Mozilla 客户端之外，许多不同的应用程序都使用 NSPR API，所以 API 必须在主要的版本之间保持向下兼容。这意味着 NSPR 中现有的公共 API 项的行为不能改变。如果您需要一个具有稍微不同行为或不同函数原型的类似 API，请建议一个具有不同名称的新 API。

C 语言 API¶

NSPR API 是一个 C 语言 API。请不要贡献 Java、C++ 或其他语言的包装器。

编码风格¶

NSPR 没有文档化的编码风格指南。请参考现有的代码。使您的代码看起来与之类似。在NSPR 命名约定中可以找到一些关于命名约定的指南，该指南位于NSPR API 参考中。

您贡献内容的所有权¶

当您向 NSPR 贡献内容时，您必须拥有该贡献的知识产权。这意味着您不能给我们提供从其他地方获取的内容；它必须是您自己的发明，不受任何人或任何事物的约束；请密切关注您“日常工作”雇主的权利。如果您从其他地方获取了它，请告诉我们来源；向我们展示将它整合到 NSPR 中的权利存在的地方。

根据 MPL 或 GPL 许可¶

当您向 NSPR 贡献材料时，您同意允许您的贡献在 MPL 或 GPL 下获得许可。

错误修复¶

使用Bugzilla跟踪错误。记录错误或使用现有的报告。详细描述您正在做什么以及原因。

将您的更改作为差异包含在 BugZilla 报告的附件中。

使用与您正在更改的源文件一致的编码风格。

新功能¶

对于本文档的目的，“新功能”被定义为添加到核心 NSPR 库中的一些 API 添加，例如：libnspr4.dll

NSPR 基本上已经完成了。新的 API 主要由操作系统供应商驱动，因为他们添加了新功能。如果您认为 NSPR 没有涵盖某些应该涵盖的内容，请告诉我们。您提出的 API 应该封装一个相对较低级别的功能，就像在系统调用或 libc 中找到的那样。

您的新功能必须在 NSPR 支持的所有平台上实现。当您考虑为 NSPR 提供新的 API 时，请询问自己您提出的功能是否可以在 NSPR 支持的所有平台上实现它。如果几个平台无法实现您的 API，那么它不适合包含在 NSPR 中。

在您开始为 NSPR 创建候选功能的大量工作之前，请与我们联系。我们可能会告诉您您的想法很好；我们可能会说它真的不适合包含在 NSPR 中；我们可能会给您一些建议，让它变得更通用，从而成为包含在 NSPR 中的良好候选者。

使用Bugzilla跟踪您的工作。请详细描述。

NSPR 希望您记录您的工作。如果我们接受它，我们将不得不回答有关它的问题和/或维护它。以下是一些关于您可以添加到 NSPR 的新 API 的指南。

**头文件描述**。提供头文件描述，全面记录您的公共类型定义、枚举、宏和函数。

请参见：prshm.h 作为您头文件应如何记录的示例。

源文件描述*o. 在您的源 (.c) 文件中提供描述性文档。唉，我们没有像我们认为应该那样记录的源文件。

以下是一些在实现新功能时应遵循的通用指南

不要导出全局变量
您的代码必须是线程安全的
您必须提供测试用例来测试您添加的所有 API。请参见：[#TestCases 测试用例]

新库¶

适用于 [#NewFeatures 新功能] 的所有指南也适用于新库。

对于本文档的目的，“新库”被定义为 mozilla/nsprpub/lib 目录树下的库，并作为单独的库构建。这些库在很大程度上是 NSPR 1.0 中的“遗留”代码。[请注意，当前的 NSPR 模块所有者现在没有也不曾参与过 NSPR 1.0。] 这就是生活。也就是说：有一些库实现了旨在与使用 NSPR 的应用程序一起使用的函数，例如 ...nsprpub/lib/libc/plgetopt.*.

通常有用
平台抽象
您同意维护、修复错误
可以依赖 NSPR API
不能依赖任何其他库 API

新平台移植¶

必须实现所有 NSPR API 项
平台特定的头文件位于 pr/include/md/_platformname.[h!cfg] 中
平台特定的代码位于 pr/src/md/platform/*.c 中
make 规则位于 config/_platform.mk 中

文档¶

NSPR 文档的文件使用专有的文字处理系统维护[不要问]。如 [#NewFeatures 新功能] 中所述，记录您的工作。使用其他 NSPR 文档的样式。我们会确保您的文档被转录到相应的文字处理器中，并且派生的 HTML 会显示在 mozilla.org 上

测试用例¶

您应该为所有新功能和新库提供测试用例。

在修复错误时，如果现有的测试用例没有捕获它应该捕获的错误，请考虑提供测试用例。

新的测试用例应该以其他 NSPR 测试用例的风格实现。

测试用例应该证明添加的 API 项按预期工作。

测试用例应该作为如何使用 API 项的示例。

测试用例应该引发每个 API 项的失败并报告其失败。

常见问题解答 (FAQ)¶

问：为什么我的贡献被拒绝了？

答：检查涵盖您贡献的 Bugzilla 报告。